npm - @softspark/ai-toolkit - Versions diffs - 4.29.2 → 4.30.2 - Mend

@softspark/ai-toolkit 4.29.2 → 4.30.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (42) hide show

package/CHANGELOG.md +82 -0
package/README.md +44 -18
package/app/.claude-plugin/plugin.json +1 -1
package/app/ARCHITECTURE.md +2 -2
package/app/mcp-templates/README.md +7 -2
package/app/mcp-templates/rag-mcp-legal.json +11 -0
package/app/mcp-templates/rag-mcp.json +11 -0
package/app/surface.json +1 -0
package/benchmarks/ecosystem-doctor-snapshot.json +29 -17
package/bin/ai-toolkit.js +8 -0
package/kb/history/completed/dsh-integration-plan-superseded.md +322 -0
package/kb/history/completed/dsh-native-install-target-plan.md +331 -0
package/kb/procedures/ecosystem-sync-sop.md +7 -5
package/kb/procedures/maintenance-sop.md +1 -1
package/kb/procedures/release-verification-sop.md +35 -5
package/kb/reference/architecture-overview.md +24 -5
package/kb/reference/cli-reference.md +1 -1
package/kb/reference/dsh-compatibility.md +183 -0
package/kb/reference/manifest-install.md +112 -5
package/kb/reference/mcp-templates.md +11 -4
package/kb/reference/plugin-pack-conventions.md +35 -18
package/kb/reference/supported-tools-registry.md +30 -6
package/llms-full.txt +1110 -50
package/llms.txt +3 -0
package/manifest.json +2 -2
package/package.json +2 -2
package/scripts/codex_skill_adapter.py +673 -34
package/scripts/config_resolver.py +80 -14
package/scripts/doctor.py +98 -20
package/scripts/ecosystem_tools.json +51 -1
package/scripts/generate_codex_skills.py +22 -20
package/scripts/install.py +30 -13
package/scripts/install_steps/ai_tools.py +97 -33
package/scripts/install_steps/dsh.py +5063 -0
package/scripts/install_steps/install_state.py +1645 -57
package/scripts/mcp_editors.py +5 -2
package/scripts/plugin.py +2495 -163
package/scripts/plugin_mcp.py +279 -0
package/scripts/plugin_rules.py +389 -0
package/scripts/plugin_schema.py +139 -23
package/scripts/uninstall.py +47 -4
package/scripts/validate.py +421 -0

package/scripts/codex_skill_adapter.py CHANGED Viewed

@@ -2,12 +2,12 @@
 # Copyright 2024-2026 Lukasz Krzemien (biuro@softspark.eu)
 # Source: https://github.com/softspark/ai-toolkit
-"""Adapt ai-toolkit skills for Codex CLI.
+"""Adapt ai-toolkit skills for clients sharing ``.agents/skills``.
 Compatible skills are symlinked as-is. Skills that rely on Claude-only
-delegation primitives are rendered into Codex-specific wrappers that keep the
-same references/assets but rewrite the main SKILL.md guidance to use native
-Codex subagents and plan tracking.
+delegation primitives are rendered into Codex-specific or portable DSH
+wrappers. Generated variants retain shared references and assets while using
+guidance appropriate for the selected discovery-surface owners.
 """
 from __future__ import annotations
@@ -15,9 +15,11 @@ import errno
 import json
 import os
 import re
+import stat
 import sys
 import tempfile
 from pathlib import Path
+from typing import NamedTuple
 try:
     from frontmatter import frontmatter_field
@@ -33,6 +35,15 @@ CLAUDE_ONLY_TOOLS = frozenset({
 })
 ADAPTED_MARKER = ".ai-toolkit-codex-adapted"
+DSH_ADAPTED_MARKER = ".ai-toolkit-dsh-adapted"
+SHARED_ADAPTED_MARKER = ".ai-toolkit-shared-adapted"
+SKILL_SURFACE_OWNERS_MARKER = ".ai-toolkit-skill-owners"
+ADAPTED_MARKERS = frozenset({
+    ADAPTED_MARKER,
+    DSH_ADAPTED_MARKER,
+    SHARED_ADAPTED_MARKER,
+})
+SKILL_SURFACE_OWNERS = frozenset({"codex", "dsh"})
 _FRONTMATTER_RE = re.compile(r"\A---\n(?P<frontmatter>.*?)\n---\n?(?P<body>.*)\Z", re.S)
 _AGENT_START_RE = re.compile(r"\bAgent\s*\(")
@@ -62,7 +73,48 @@ _ADAPTATION_BODY_TOKENS = frozenset({
 })
+class _OwnerMarkerState(NamedTuple):
+    data: bytes | None
+    signature: tuple[int, int, int, int, int] | None
+class _ManagedChildState(NamedTuple):
+    kind: str
+    content: bytes | str
+    permissions: int = 0
+class _ManagedEntryState(NamedTuple):
+    kind: str
+    content: str | dict[str, _ManagedChildState]
+class _RegularFileState(NamedTuple):
+    data: bytes
+    signature: tuple[int, int, int, int, int]
+    permissions: int
 def _translation_note(platform: str) -> str:
+    if platform == "dsh":
+        return """
+## Portable Translation Layer
+This generated variant preserves the workflow intent using durable,
+client-independent guidance:
+- Use available subagents when delegation materially improves speed or quality.
+- Give delegated work a narrow objective, relevant context, explicit file
+  ownership, and a clear expected result.
+- Use the controls available in the current client to steer or stop delegated
+  work without assuming a particular tool signature.
+- Wait for delegated results only when the next critical-path step depends on
+  them, then integrate the results in the parent task.
+- Track progress using the planning mechanism available in the current client
+  or an explicit local checklist.
+- Resolve `./` paths in command examples from the installed skill directory
+  that contains this `SKILL.md` file.
+"""
     label = _PLATFORM_LABELS[platform]
     return f"""
 ## {label} Translation Layer
@@ -87,6 +139,31 @@ client-independent guidance:
 def _semantic_replacements(platform: str) -> dict[str, str]:
+    if platform == "dsh":
+        return {
+            "${CLAUDE_SKILL_DIR}/": "./",
+            "$CLAUDE_SKILL_DIR/": "./",
+            "${CLAUDE_SKILL_DIR}": "the installed skill directory",
+            "CLAUDE_SKILL_DIR": "the installed skill directory",
+            "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "subagent support",
+            "spawn_agent": "delegate independent work to an available subagent",
+            "send_input": "steer a running subagent",
+            "wait_agent": "wait for delegated results",
+            "close_agent": "stop or finish delegated work",
+            "update_plan": "the planning mechanism available in the current client",
+            "fork_context": "appropriate inherited task context",
+            "agent_type=": "a suitable subagent role",
+            "TeamCreate": "coordinate available subagents",
+            "TeamDelete": "finish coordinated subagent work",
+            "SendMessage": "steer a running subagent",
+            "TaskCreate": "the available planning mechanism",
+            "TaskList": "the available planning mechanism",
+            "TaskUpdate": "the available planning mechanism",
+            "TaskGet": "review delegated progress",
+            "TaskOutput": "collect delegated results",
+            "TaskStop": "stop delegated work",
+            "$ARGUMENTS": "the user-supplied task details",
+        }
     label = _PLATFORM_LABELS[platform]
     native_subagent = f"{label}-native subagent"
     replacements = {
@@ -159,9 +236,23 @@ def build_opencode_skill_text(skill_file: Path) -> str:
     return _build_portable_skill_text(skill_file, "opencode")
+def build_dsh_skill_text(skill_file: Path) -> str:
+    """Render a platform-neutral DSH skill with invocation metadata intact."""
+    return _build_portable_skill_text(skill_file, "dsh")
+def _build_managed_skill_text(skill_file: Path, platform: str) -> str:
+    """Dispatch managed wrapper rendering without changing legacy APIs."""
+    if platform == "codex":
+        return build_codex_skill_text(skill_file)
+    if platform == "dsh":
+        return build_dsh_skill_text(skill_file)
+    raise ValueError(f"Unsupported managed skill platform: {platform}")
 def _build_portable_skill_text(skill_file: Path, platform: str) -> str:
     """Render a client-specific skill using semantic, signature-free guidance."""
-    if platform not in _PLATFORM_LABELS:
+    if platform not in {*_PLATFORM_LABELS, "dsh"}:
         raise ValueError(f"Unsupported skill adaptation platform: {platform}")
     text = skill_file.read_text(encoding="utf-8")
     match = _FRONTMATTER_RE.match(text)
@@ -179,9 +270,15 @@ def _build_portable_skill_text(skill_file: Path, platform: str) -> str:
             if platform == "codex"
             else frontmatter_field(skill_file, "description")
         )
-        rendered_frontmatter = "\n".join(
-            (f"name: {name}", f"description: {json.dumps(description, ensure_ascii=False)}")
-        )
+        rendered_entries = [
+            ("name", str(name)),
+            ("description", json.dumps(description, ensure_ascii=False)),
+        ]
+        rendered_frontmatter = _render_frontmatter(rendered_entries)
+        if platform == "dsh":
+            invocation_lines = _invocation_metadata_lines(match.group("frontmatter"))
+            if invocation_lines:
+                rendered_frontmatter += "\n" + "\n".join(invocation_lines)
     else:
         frontmatter = _parse_frontmatter(match.group("frontmatter"))
         rendered_frontmatter = _render_frontmatter(frontmatter)
@@ -199,8 +296,23 @@ def sync_codex_skill(skill_dir: Path, skills_dst: Path) -> str:
     return _sync_native_skill(skill_dir, skills_dst)
+def sync_dsh_skill(skill_dir: Path, skills_dst: Path, *, shared: bool = False) -> str:
+    """Install one skill for DSH, optionally on a Codex-shared surface."""
+    skill_file = skill_dir / "SKILL.md"
+    if not is_codex_adapted_skill(skill_file):
+        return _sync_native_skill(skill_dir, skills_dst)
+    marker = SHARED_ADAPTED_MARKER if shared else DSH_ADAPTED_MARKER
+    return _sync_adapted_skill(
+        skill_dir,
+        skills_dst,
+        platform="dsh",
+        marker_name=marker,
+    )
 def prepare_codex_skills_dir(target_dir: Path) -> Path:
     """Create the documented Codex skill root without following symlinks."""
+    _preflight_skill_surface_owner_marker(target_dir)
     if target_dir.is_symlink():
         raise RuntimeError(f"Refusing symlinked Codex target directory: {target_dir}")
     agents_dir = target_dir / ".agents"
@@ -211,6 +323,373 @@ def prepare_codex_skills_dir(target_dir: Path) -> Path:
     return skills_dst
+def _preflight_skill_surface_owner_marker(target_dir: Path) -> _OwnerMarkerState:
+    """Validate and snapshot ownership before any skill-root mutation."""
+    return _read_owner_marker_state(
+        target_dir / ".agents" / SKILL_SURFACE_OWNERS_MARKER
+    )
+def _read_owner_marker_state(marker: Path) -> _OwnerMarkerState:
+    """Return the exact valid marker state, rejecting every unsafe collision."""
+    if marker.is_symlink():
+        raise RuntimeError(
+            f"Refusing invalid skill-surface owner marker {marker}: "
+            "symlinks are not managed owner markers"
+        )
+    if not marker.exists():
+        return _OwnerMarkerState(data=None, signature=None)
+    try:
+        metadata = marker.lstat()
+    except OSError as error:
+        raise RuntimeError(
+            f"Refusing invalid skill-surface owner marker {marker}: "
+            f"cannot inspect marker ({error})"
+        ) from error
+    if stat.S_ISDIR(metadata.st_mode):
+        raise RuntimeError(
+            f"Refusing invalid skill-surface owner marker {marker}: "
+            "directory found where a regular marker file is required"
+        )
+    if not stat.S_ISREG(metadata.st_mode):
+        raise RuntimeError(
+            f"Refusing invalid skill-surface owner marker {marker}: "
+            "only a regular non-symlink marker file is supported"
+        )
+    try:
+        data = marker.read_bytes()
+    except (OSError, UnicodeError) as error:
+        raise RuntimeError(
+            f"Refusing invalid skill-surface owner marker {marker}: "
+            f"cannot read regular marker ({error})"
+        ) from error
+    if parse_skill_surface_owners(data) is None:
+        raise RuntimeError(
+            f"Refusing invalid skill-surface owner marker {marker}: expected "
+            "one canonical owner per line (codex and/or dsh)"
+        )
+    signature = (
+        metadata.st_dev,
+        metadata.st_ino,
+        metadata.st_mode,
+        metadata.st_size,
+        metadata.st_mtime_ns,
+    )
+    return _OwnerMarkerState(data=data, signature=signature)
+def serialize_skill_surface_owners(owners: set[str]) -> bytes:
+    """Serialize one non-empty known owner set into its only managed form."""
+    if not owners or not owners <= SKILL_SURFACE_OWNERS:
+        raise ValueError(f"Invalid .agents/skills owners: {sorted(owners)}")
+    return ("\n".join(sorted(owners)) + "\n").encode("utf-8")
+def parse_skill_surface_owners(data: bytes) -> set[str] | None:
+    """Return owners only when bytes exactly match the canonical serialization."""
+    try:
+        lines = data.decode("utf-8").splitlines()
+    except UnicodeError:
+        return None
+    owners = set(lines)
+    if len(lines) != len(owners):
+        return None
+    try:
+        canonical = serialize_skill_surface_owners(owners)
+    except ValueError:
+        return None
+    return owners if data == canonical else None
+def _assert_owner_marker_state(marker: Path, expected: _OwnerMarkerState) -> None:
+    try:
+        actual = _read_owner_marker_state(marker)
+    except RuntimeError as error:
+        raise RuntimeError(
+            f"Skill-surface owner marker changed before atomic replacement: {marker}"
+        ) from error
+    if actual != expected:
+        raise RuntimeError(
+            f"Skill-surface owner marker changed before atomic replacement: {marker}"
+        )
+def _restore_owner_marker(marker: Path, expected: _OwnerMarkerState) -> None:
+    try:
+        actual = _read_owner_marker_state(marker)
+    except RuntimeError as error:
+        raise RuntimeError(
+            f"Cannot restore changed skill-surface owner marker: {marker}"
+        ) from error
+    if actual == expected:
+        return
+    if expected.data is None:
+        if actual.data is None:
+            return
+        marker.unlink()
+        _fsync_directory(marker.parent)
+        return
+    temp_path = _stage_bytes(marker, expected.data)
+    try:
+        os.replace(temp_path, marker)
+        _fsync_directory(marker.parent)
+    finally:
+        temp_path.unlink(missing_ok=True)
+def _directory_entry_names(path: Path) -> set[str]:
+    if not path.is_dir() or path.is_symlink():
+        return set()
+    return {entry.name for entry in path.iterdir()}
+def _snapshot_managed_entries(
+    skills_dst: Path,
+    skills_src: Path,
+) -> dict[str, _ManagedEntryState]:
+    if not skills_dst.is_dir() or skills_dst.is_symlink():
+        return {}
+    source_root = skills_src.resolve()
+    snapshots: dict[str, _ManagedEntryState] = {}
+    for entry in skills_dst.iterdir():
+        if entry.is_symlink():
+            if _is_relative_to(_symlink_target(entry), source_root):
+                snapshots[entry.name] = _ManagedEntryState(
+                    kind="link",
+                    content=os.readlink(entry),
+                )
+            continue
+        marker_name = _validated_wrapper_marker(entry)
+        if marker_name is None:
+            continue
+        children: dict[str, _ManagedChildState] = {}
+        for child in entry.iterdir():
+            if child.name == "SKILL.md" or child.name in ADAPTED_MARKERS:
+                if child.is_symlink() or not child.is_file():
+                    raise RuntimeError(
+                        f"Cannot transactionally manage malformed skill wrapper: {child}"
+                    )
+                metadata = child.stat()
+                children[child.name] = _ManagedChildState(
+                    kind="file",
+                    content=child.read_bytes(),
+                    permissions=stat.S_IMODE(metadata.st_mode),
+                )
+                continue
+            if child.is_symlink() and _is_relative_to(
+                _symlink_target(child), source_root
+            ):
+                children[child.name] = _ManagedChildState(
+                    kind="link",
+                    content=os.readlink(child),
+                )
+        if "SKILL.md" not in children or marker_name not in children:
+            raise RuntimeError(f"Cannot snapshot incomplete skill wrapper: {entry}")
+        snapshots[entry.name] = _ManagedEntryState(
+            kind="wrapper",
+            content=children,
+        )
+    return snapshots
+def _validated_wrapper_marker(path: Path) -> str | None:
+    if path.is_symlink() or not path.is_dir():
+        return None
+    present = [
+        marker_name
+        for marker_name in sorted(ADAPTED_MARKERS)
+        if (path / marker_name).exists() or (path / marker_name).is_symlink()
+    ]
+    if not present:
+        return None
+    if len(present) != 1:
+        raise RuntimeError(f"Ambiguous managed skill wrapper markers: {path}")
+    marker = path / present[0]
+    if marker.is_symlink() or not marker.is_file():
+        raise RuntimeError(f"Malformed managed skill wrapper marker: {marker}")
+    return present[0]
+def _remove_transaction_entry(path: Path, source_root: Path) -> None:
+    if path.is_symlink():
+        if _is_relative_to(_symlink_target(path), source_root):
+            path.unlink()
+        return
+    if not path.is_dir():
+        return
+    if _validated_wrapper_marker(path) is None:
+        return
+    _remove_transaction_children(path, source_root)
+    try:
+        path.rmdir()
+    except OSError:
+        pass
+def _remove_transaction_children(path: Path, source_root: Path) -> None:
+    for child in list(path.iterdir()):
+        if child.name == "SKILL.md" or child.name in ADAPTED_MARKERS:
+            if child.is_symlink() or child.is_file():
+                child.unlink()
+            continue
+        if child.is_symlink() and _is_relative_to(
+            _symlink_target(child), source_root
+        ):
+            child.unlink()
+def _restore_managed_entry(
+    path: Path,
+    expected: _ManagedEntryState,
+    source_root: Path,
+) -> None:
+    if expected.kind == "link":
+        _remove_transaction_entry(path, source_root)
+        if path.exists() or path.is_symlink():
+            if path.is_symlink() and os.readlink(path) == expected.content:
+                return
+            raise RuntimeError(f"Cannot restore managed skill link without data loss: {path}")
+        path.symlink_to(str(expected.content))
+        return
+    if path.is_symlink():
+        if not _is_relative_to(_symlink_target(path), source_root):
+            raise RuntimeError(f"Cannot replace user-owned skill link: {path}")
+        path.unlink()
+    if path.exists() and not path.is_dir():
+        raise RuntimeError(f"Cannot restore managed skill wrapper: {path}")
+    path.mkdir(exist_ok=True)
+    _remove_transaction_children(path, source_root)
+    children = expected.content
+    if not isinstance(children, dict):
+        raise RuntimeError(f"Invalid managed wrapper snapshot: {path}")
+    for name, child_state in children.items():
+        destination = path / name
+        if child_state.kind == "link":
+            destination.symlink_to(str(child_state.content))
+            continue
+        data = child_state.content
+        if not isinstance(data, bytes):
+            raise RuntimeError(f"Invalid managed file snapshot: {destination}")
+        temp_path = _stage_bytes(destination, data)
+        try:
+            os.chmod(temp_path, child_state.permissions)
+            os.replace(temp_path, destination)
+        finally:
+            temp_path.unlink(missing_ok=True)
+    _fsync_directory(path)
+def set_skill_surface_owners(
+    skills_dst: Path,
+    owners: set[str],
+    *,
+    expected_state: _OwnerMarkerState | None = None,
+) -> None:
+    """Record explicit owners for the otherwise ambiguous shared directory."""
+    _assert_safe_skill_roots(skills_dst.parent, skills_dst)
+    marker = skills_dst.parent / SKILL_SURFACE_OWNERS_MARKER
+    previous = expected_state or _read_owner_marker_state(marker)
+    temp_path = _stage_bytes(marker, serialize_skill_surface_owners(owners))
+    try:
+        _assert_owner_marker_state(marker, previous)
+        os.replace(temp_path, marker)
+        _fsync_directory(skills_dst.parent)
+    finally:
+        temp_path.unlink(missing_ok=True)
+def skill_surface_owners(skills_dst: Path) -> set[str] | None:
+    """Return declared owners, ``None`` for a legacy unowned surface."""
+    marker = skills_dst.parent / SKILL_SURFACE_OWNERS_MARKER
+    try:
+        state = _read_owner_marker_state(marker)
+    except RuntimeError:
+        return set()
+    if state.data is None:
+        return None
+    owners = parse_skill_surface_owners(state.data)
+    return owners if owners is not None else set()
+class _SkillSurfaceTransaction:
+    """Rollback guard for the installer-owned portion of `.agents/skills`."""
+    def __init__(self, target_dir: Path, skills_src: Path) -> None:
+        self.target_dir = target_dir
+        self.skills_src = skills_src
+        self.agents_dir = target_dir / ".agents"
+        self.skills_dst = self.agents_dir / "skills"
+        self.marker = self.agents_dir / SKILL_SURFACE_OWNERS_MARKER
+        self.marker_state = _read_owner_marker_state(self.marker)
+        self.agents_existed = self.agents_dir.is_dir()
+        self.skills_existed = self.skills_dst.is_dir()
+        _assert_safe_skill_roots(self.agents_dir, self.skills_dst)
+        self.entries = _snapshot_managed_entries(self.skills_dst, skills_src)
+        self.initial_names = _directory_entry_names(self.skills_dst)
+        self.is_committed = False
+    def __enter__(self) -> _SkillSurfaceTransaction:
+        self.skills_dst = prepare_codex_skills_dir(self.target_dir)
+        return self
+    def commit(self, owners: set[str]) -> None:
+        set_skill_surface_owners(
+            self.skills_dst,
+            owners,
+            expected_state=self.marker_state,
+        )
+        self.is_committed = True
+    def __exit__(self, error_type, error, traceback) -> bool:
+        if error is None and self.is_committed:
+            return False
+        try:
+            self._rollback()
+        except (OSError, RuntimeError) as rollback_error:
+            if error is None:
+                raise
+            raise RuntimeError(
+                f"Managed skill transaction failed and rollback was incomplete: "
+                f"{rollback_error}"
+            ) from error
+        return False
+    def _rollback(self) -> None:
+        if self.skills_dst.is_dir() and not self.skills_dst.is_symlink():
+            current_names = _directory_entry_names(self.skills_dst)
+            for name in sorted(current_names - self.initial_names):
+                _remove_transaction_entry(
+                    self.skills_dst / name,
+                    self.skills_src.resolve(),
+                )
+            for name, entry_state in self.entries.items():
+                _restore_managed_entry(
+                    self.skills_dst / name,
+                    entry_state,
+                    self.skills_src.resolve(),
+                )
+        _restore_owner_marker(self.marker, self.marker_state)
+        if not self.skills_existed and self.skills_dst.is_dir():
+            try:
+                self.skills_dst.rmdir()
+            except OSError:
+                pass
+        if not self.agents_existed and self.agents_dir.is_dir():
+            try:
+                self.agents_dir.rmdir()
+            except OSError:
+                pass
+def managed_skill_surface_transaction(
+    target_dir: Path,
+    skills_src: Path,
+) -> _SkillSurfaceTransaction:
+    """Return a rollback guard for one complete managed skill installation."""
+    return _SkillSurfaceTransaction(target_dir, skills_src)
 def unmanaged_codex_skill_names(skills_dst: Path, skills_src: Path) -> set[str]:
     """Return logical names declared by user-owned destination entries."""
     names: set[str] = set()
@@ -273,11 +752,18 @@ def _points_to(path: Path, target: Path) -> bool:
     return path.is_symlink() and _symlink_target(path) == target.resolve()
-def _is_adapted_wrapper(path: Path) -> bool:
+def _adapted_marker(path: Path) -> str | None:
     if path.is_symlink() or not path.is_dir():
-        return False
-    marker = path / ADAPTED_MARKER
-    return not marker.is_symlink() and marker.is_file()
+        return None
+    for marker_name in sorted(ADAPTED_MARKERS):
+        marker = path / marker_name
+        if not marker.is_symlink() and marker.is_file():
+            return marker_name
+    return None
+def _is_adapted_wrapper(path: Path) -> bool:
+    return _adapted_marker(path) is not None
 def _is_managed_entry(path: Path, skills_src: Path) -> bool:
@@ -301,18 +787,102 @@ def _sync_native_skill(skill_dir: Path, skills_dst: Path) -> str:
     return "linked"
-def _sync_adapted_skill(skill_dir: Path, skills_dst: Path) -> str:
+def _sync_adapted_skill(
+    skill_dir: Path,
+    skills_dst: Path,
+    *,
+    platform: str = "codex",
+    marker_name: str = ADAPTED_MARKER,
+) -> str:
     target = skills_dst / skill_dir.name
     if target.is_symlink():
         if not _points_to(target, skill_dir):
             return "skipped"
-        return _create_adapted_wrapper(skill_dir, target, replace_managed_link=True)
+        return _create_adapted_wrapper(
+            skill_dir,
+            target,
+            replace_managed_link=True,
+            platform=platform,
+            marker_name=marker_name,
+        )
     if target.exists() and not _is_adapted_wrapper(target):
         return "skipped"
     if not target.exists():
-        return _create_adapted_wrapper(skill_dir, target)
+        return _create_adapted_wrapper(
+            skill_dir,
+            target,
+            platform=platform,
+            marker_name=marker_name,
+        )
+    if _adapted_marker(target) != marker_name:
+        return _transition_adapted_wrapper(
+            skill_dir,
+            target,
+            platform=platform,
+            marker_name=marker_name,
+        )
+    return _update_adapted_wrapper(
+        skill_dir,
+        target,
+        platform=platform,
+        marker_name=marker_name,
+    )
-    return _update_adapted_wrapper(skill_dir, target)
+def _transition_adapted_wrapper(
+    skill_dir: Path,
+    target: Path,
+    *,
+    platform: str,
+    marker_name: str,
+) -> str:
+    """Replace only managed wrapper files while preserving user additions."""
+    previous_marker_name = _validated_wrapper_marker(target)
+    if previous_marker_name is None:
+        return "skipped"
+    skill_output = target / "SKILL.md"
+    previous_marker = target / previous_marker_name
+    next_marker = target / marker_name
+    if skill_output.is_symlink() or not skill_output.is_file():
+        return "skipped"
+    if next_marker.exists() or next_marker.is_symlink():
+        return "skipped"
+    skill_state = _regular_file_state(skill_output)
+    marker_state = _regular_file_state(previous_marker)
+    next_skill = _stage_text(
+        skill_output,
+        _build_managed_skill_text(skill_dir / "SKILL.md", platform),
+    )
+    next_marker_file = _stage_text(
+        next_marker,
+        f"generated by ai-toolkit for {platform}\n",
+    )
+    try:
+        _assert_regular_file_state(skill_output, skill_state)
+        _assert_regular_file_state(previous_marker, marker_state)
+        if next_marker.exists() or next_marker.is_symlink():
+            raise RuntimeError(f"Managed skill marker appeared during sync: {next_marker}")
+        os.replace(next_skill, skill_output)
+        os.replace(next_marker_file, next_marker)
+        _assert_regular_file_state(previous_marker, marker_state)
+        previous_marker.unlink()
+        _sync_auxiliaries(skill_dir, target)
+        _fsync_directory(target)
+    except Exception:
+        _restore_regular_file(skill_output, skill_state)
+        if next_marker.is_file() and not next_marker.is_symlink():
+            expected = f"generated by ai-toolkit for {platform}\n".encode("utf-8")
+            if next_marker.read_bytes() == expected:
+                next_marker.unlink()
+        _restore_regular_file(previous_marker, marker_state)
+        raise
+    finally:
+        next_skill.unlink(missing_ok=True)
+        next_marker_file.unlink(missing_ok=True)
+    return "adapted"
 def _create_adapted_wrapper(
@@ -320,6 +890,8 @@ def _create_adapted_wrapper(
     target: Path,
     *,
     replace_managed_link: bool = False,
+    platform: str = "codex",
+    marker_name: str = ADAPTED_MARKER,
 ) -> str:
     """Build a complete sibling wrapper and expose it with one atomic rename."""
     staging = Path(tempfile.mkdtemp(
@@ -331,11 +903,11 @@ def _create_adapted_wrapper(
     try:
         _write_text_fsync(
             staging / "SKILL.md",
-            build_codex_skill_text(skill_dir / "SKILL.md"),
+            _build_managed_skill_text(skill_dir / "SKILL.md", platform),
         )
         _write_text_fsync(
-            staging / ADAPTED_MARKER,
-            "generated by ai-toolkit for Codex\n",
+            staging / marker_name,
+            f"generated by ai-toolkit for {platform}\n",
         )
         _sync_auxiliaries(skill_dir, staging)
         _fsync_directory(staging)
@@ -358,15 +930,21 @@ def _create_adapted_wrapper(
         raise
-def _update_adapted_wrapper(skill_dir: Path, target: Path) -> str:
+def _update_adapted_wrapper(
+    skill_dir: Path,
+    target: Path,
+    *,
+    platform: str = "codex",
+    marker_name: str = ADAPTED_MARKER,
+) -> str:
     """Atomically refresh SKILL.md while leaving the managed marker stable."""
     skill_output = target / "SKILL.md"
-    marker = target / ADAPTED_MARKER
+    marker = target / marker_name
     if skill_output.is_symlink() or marker.is_symlink():
         return "skipped"
     temp_path = _stage_text(
         skill_output,
-        build_codex_skill_text(skill_dir / "SKILL.md"),
+        _build_managed_skill_text(skill_dir / "SKILL.md", platform),
     )
     try:
         os.replace(temp_path, skill_output)
@@ -384,6 +962,44 @@ def _write_text_fsync(destination: Path, content: str) -> None:
         os.fsync(handle.fileno())
+def _regular_file_state(path: Path) -> _RegularFileState:
+    if path.is_symlink() or not path.is_file():
+        raise RuntimeError(f"Managed file is not a regular non-symlink file: {path}")
+    metadata = path.stat()
+    return _RegularFileState(
+        data=path.read_bytes(),
+        signature=(
+            metadata.st_dev,
+            metadata.st_ino,
+            metadata.st_mode,
+            metadata.st_size,
+            metadata.st_mtime_ns,
+        ),
+        permissions=stat.S_IMODE(metadata.st_mode),
+    )
+def _assert_regular_file_state(path: Path, expected: _RegularFileState) -> None:
+    actual = _regular_file_state(path)
+    if actual != expected:
+        raise RuntimeError(f"Managed file changed during skill sync: {path}")
+def _restore_regular_file(path: Path, expected: _RegularFileState) -> None:
+    try:
+        if _regular_file_state(path).data == expected.data:
+            return
+    except RuntimeError:
+        if path.exists() or path.is_symlink():
+            raise
+    staged = _stage_bytes(path, expected.data)
+    try:
+        os.chmod(staged, expected.permissions)
+        os.replace(staged, path)
+    finally:
+        staged.unlink(missing_ok=True)
 def _fsync_directory(path: Path) -> None:
     if os.name == "nt":
         return
@@ -417,6 +1033,10 @@ def _remove_staged_wrapper(staging: Path) -> None:
 def _stage_text(destination: Path, content: str) -> Path:
+    return _stage_bytes(destination, content.encode("utf-8"))
+def _stage_bytes(destination: Path, content: bytes) -> Path:
     fd, temp_name = tempfile.mkstemp(
         dir=destination.parent,
         prefix=f".{destination.name}.",
@@ -424,7 +1044,7 @@ def _stage_text(destination: Path, content: str) -> Path:
     )
     temp_path = Path(temp_name)
     try:
-        handle = os.fdopen(fd, "w", encoding="utf-8")
+        handle = os.fdopen(fd, "wb")
         fd = -1
         with handle:
             handle.write(content)
@@ -454,7 +1074,7 @@ def _sync_auxiliaries(skill_dir: Path, target: Path) -> None:
     source_root = skill_dir.resolve()
     for destination in target.iterdir():
-        if destination.name in expected | {"SKILL.md", ADAPTED_MARKER}:
+        if destination.name in expected | {"SKILL.md", *ADAPTED_MARKERS}:
             continue
         if destination.is_symlink() and _is_relative_to(
             _symlink_target(destination), source_root
@@ -466,8 +1086,11 @@ def _remove_managed_wrapper(path: Path, skills_src_resolved: Path) -> bool:
     if not _is_adapted_wrapper(path):
         return False
     children = list(path.iterdir())
+    marker_name = _adapted_marker(path)
+    if marker_name is None:
+        return False
     for child in children:
-        if child.name in {"SKILL.md", ADAPTED_MARKER}:
+        if child.name in {"SKILL.md", marker_name}:
             if child.is_symlink() or not child.is_file():
                 return False
             continue
@@ -499,17 +1122,34 @@ def _parse_frontmatter(frontmatter_text: str) -> list[tuple[str, str]]:
     return entries
+def _invocation_metadata_lines(frontmatter_text: str) -> list[str]:
+    """Return exact canonical invocation lines, rejecting duplicate fields."""
+    fields = ("user-invocable", "disable-model-invocation")
+    lines: list[str] = []
+    seen: set[str] = set()
+    for line in frontmatter_text.splitlines():
+        field = next((name for name in fields if line.startswith(f"{name}:")), None)
+        if field is None:
+            continue
+        if field in seen:
+            raise ValueError(f"Duplicate invocation metadata field: {field}")
+        seen.add(field)
+        lines.append(line)
+    return lines
 def _render_frontmatter(entries: list[tuple[str, str]]) -> str:
     return "\n".join(f"{key}: {value}" for key, value in entries)
 def _adapt_body(body: str, platform: str) -> str:
-    label = _PLATFORM_LABELS[platform]
+    label = _PLATFORM_LABELS.get(platform)
     body = _replace_agent_calls(body, label)
-    body = body.replace("Agent Teams", f"coordinated {label}-native subagents")
-    body = body.replace("`Agent` tool", f"{label}-native subagents")
-    body = body.replace("the `Agent` tool", f"{label}-native subagents")
-    body = body.replace("Agent tool", f"{label}-native subagents")
+    subagents = f"{label}-native subagents" if label else "available subagents"
+    body = body.replace("Agent Teams", f"coordinated {subagents}")
+    body = body.replace("`Agent` tool", subagents)
+    body = body.replace("the `Agent` tool", subagents)
+    body = body.replace("Agent tool", subagents)
     for token, replacement in _semantic_replacements(platform).items():
         body = body.replace(token, replacement)
     if platform == "codex":
@@ -520,16 +1160,15 @@ def _adapt_body(body: str, platform: str) -> str:
     return f"{_translation_note(platform).strip()}\n\n{body.strip()}\n"
-def _replace_agent_calls(body: str, label: str) -> str:
+def _replace_agent_calls(body: str, label: str | None) -> str:
     """Replace balanced Agent calls without consuming surrounding markdown."""
     rendered: list[str] = []
     cursor = 0
     while match := _AGENT_START_RE.search(body, cursor):
         rendered.append(body[cursor:match.start()])
         end = _balanced_call_end(body, match.end() - 1)
-        rendered.append(
-            f"Delegate this independent work to a suitable {label}-native subagent."
-        )
+        target = f"a suitable {label}-native subagent" if label else "an available subagent"
+        rendered.append(f"Delegate this independent work to {target}.")
         cursor = end
     rendered.append(body[cursor:])
     return "".join(rendered)