Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
"""Avibe-owned Skill discovery, catalog rendering, loading, and built-ins."""
from __future__ import annotations
import errno
import html
import logging
import os
import re
import stat
import unicodedata
from dataclasses import dataclass, replace
from pathlib import Path
from typing import Any, Callable, Sequence, TypeVar
import yaml
from config import paths
from core.prompt_registry import RenderedPromptBlock, join_prompt_blocks, render_prompt_block
try:
import tomllib
except ModuleNotFoundError: # pragma: no cover - Python 3.10 compatibility
import tomli as tomllib
logger = logging.getLogger(__name__)
SKILL_WORKING_DIR_ENV = "AVIBE_SKILL_WORKING_DIR"
SKILL_PROJECT_BASE_ENV = "AVIBE_SKILL_PROJECT_BASE"
BUILTIN_SKILLS_ROOT_ENV = "AVIBE_BUILTIN_SKILLS_ROOT"
BUILTIN_SKILLS_SNAPSHOT_ENV = "AVIBE_BUILTIN_SKILLS_SNAPSHOT_ID"
SKILL_HOME_ENV = "AVIBE_SKILL_HOME"
SKILL_CODEX_HOME_ENV = "AVIBE_SKILL_CODEX_HOME"
SKILL_CLAUDE_HOME_ENV = "AVIBE_SKILL_CLAUDE_HOME"
SKILL_XDG_CONFIG_HOME_ENV = "AVIBE_SKILL_XDG_CONFIG_HOME"
CATALOG_PAGE_SIZE = 25
CATALOG_PAGE_MAX_BYTES = 16 * 1024
T = TypeVar("T")
CATALOG_DESCRIPTION_MAX_CHARS = 1024
FRONTMATTER_MAX_BYTES = 64 * 1024
SKILL_BODY_MAX_BYTES = 256 * 1024
DISCOVERY_ROOT_MAX_CHILDREN = 1024
DISCOVERY_CLASS_MAX_CANDIDATES = 1024
DISCOVERY_CLASS_MAX_FRONTMATTER_BYTES = 8 * 1024 * 1024
DISCOVERY_CLASS_MAX_CHILDREN = 4096
PROJECT_ROOT_MAX_DIRECTORIES = 128
BUILTIN_TREE_MAX_ENTRIES = 4096
BUILTIN_TREE_MAX_BYTES = 32 * 1024 * 1024
_LEGACY_SNAPSHOT_ID_RE = re.compile(r"^[0-9a-f]{64}$")
_PORTABLE_NAME_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
_TOP_LEVEL_FIELD_RE = re.compile(r"^[^ \t#][^:]*:")
_BLOCK_SCALAR_RE = re.compile(r"^[|>][+-]?[1-9]?$|^[|>][1-9]?[+-]?$")
_CATALOG_FIELDS = frozenset({"name", "description", "disable-model-invocation"})
_WINDOWS_RESERVED = {
"con",
"prn",
"aux",
"nul",
*(f"com{index}" for index in range(1, 10)),
*(f"lpt{index}" for index in range(1, 10)),
}
_WINDOWS_INVALID_CHARS = frozenset('<>:"\\|?*')
_GENERATED_BYTECODE_SUFFIXES = (".pyc", ".pyo")
_PROJECT_FAMILIES = (
(Path(".agents/skills"), 1),
(Path(".codex/skills"), 2),
(Path(".claude/skills"), 3),
(Path(".opencode/skills"), 4),
)
@dataclass(frozen=True)
class ManagedSkill:
name: str
description: str
directory: Path
priority: tuple[object, ...]
body: str | None = None
directory_identity: tuple[int, int] | None = None
source_directory: Path | None = None
source_directory_identity: tuple[int, int] | None = None
frontmatter_bytes: int = 0
disable_model_invocation: bool = False
@dataclass
class _DiscoveryBudget:
candidates: int = 0
frontmatter_bytes: int = 0
direct_children: int = 0
@property
def exhausted(self) -> bool:
return (
self.candidates >= DISCOVERY_CLASS_MAX_CANDIDATES
or self.frontmatter_bytes >= DISCOVERY_CLASS_MAX_FRONTMATTER_BYTES
or self.direct_children >= DISCOVERY_CLASS_MAX_CHILDREN
)
@property
def parse_exhausted(self) -> bool:
return (
self.candidates >= DISCOVERY_CLASS_MAX_CANDIDATES
or self.frontmatter_bytes >= DISCOVERY_CLASS_MAX_FRONTMATTER_BYTES
)
@property
def remaining_frontmatter(self) -> int:
return max(0, DISCOVERY_CLASS_MAX_FRONTMATTER_BYTES - self.frontmatter_bytes)
@property
def remaining_children(self) -> int:
return max(0, DISCOVERY_CLASS_MAX_CHILDREN - self.direct_children)
@dataclass(frozen=True)
class _SnapshotEntry:
path: Path
relative: str
relative_bytes: bytes
is_directory: bool
token: tuple[int, int, int, int, int]
def _strip_yaml_comment(value: str) -> str:
single_quoted = False
double_quoted = False
escaped = False
index = 0
while index < len(value):
char = value[index]
if double_quoted:
if escaped:
escaped = False
elif char == "\\":
escaped = True
elif char == '"':
double_quoted = False
elif single_quoted:
if char == "'" and index + 1 < len(value) and value[index + 1] == "'":
index += 1
elif char == "'":
single_quoted = False
elif char == "'":
single_quoted = True
elif char == '"':
double_quoted = True
elif char == "#" and (index == 0 or value[index - 1].isspace()):
return value[:index].rstrip()
index += 1
return value.rstrip()
def _decode_scalar(value: str) -> str:
value = value.strip()
try:
node = yaml.compose(value, Loader=yaml.BaseLoader)
except Exception:
node = None
if isinstance(node, yaml.ScalarNode):
return node.value.strip()
return value.strip()
def _quoted_scalar_is_closed(value: str) -> bool:
"""Return whether a leading YAML quote has a matching closing quote."""
if not value or value[0] not in {"'", '"'}:
return True
quote = value[0]
escaped = False
index = 1
while index < len(value):
char = value[index]
if quote == '"':
if escaped:
escaped = False
elif char == "\\":
escaped = True
elif char == quote:
return True
elif char == quote:
if index + 1 < len(value) and value[index + 1] == quote:
index += 1
else:
return True
index += 1
return False
def _normalize_description(value: str) -> str:
without_controls = "".join(" " if unicodedata.category(char).startswith("C") else char for char in value)
return " ".join(without_controls.split())
class _BoundedBaseLoader(yaml.BaseLoader):
"""Compose bounded YAML nodes without constructing optional typed values."""
def __init__(self, stream: str) -> None:
super().__init__(stream)
self._composed_nodes = 0
self._aliases = 0
def compose_node(self, parent, index):
if self.check_event(yaml.AliasEvent):
self._aliases += 1
if self._aliases > 128:
raise yaml.YAMLError("frontmatter contains too many YAML aliases")
else:
self._composed_nodes += 1
if self._composed_nodes > 1024:
raise yaml.YAMLError("frontmatter contains too many YAML nodes")
return super().compose_node(parent, index)
def _normalize_frontmatter_value(field: str, value: str) -> str:
return _normalize_description(value) if field == "description" else value.strip()
def _structured_frontmatter_fields(frontmatter: str) -> dict[str, str]:
"""Read only the root scalar fields needed by the managed catalog."""
try:
node = yaml.compose(frontmatter, Loader=_BoundedBaseLoader)
except Exception:
return {}
if not isinstance(node, yaml.MappingNode):
return {}
fields: dict[str, str] = {}
for key_node, value_node in node.value:
if not isinstance(key_node, yaml.ScalarNode) or not isinstance(value_node, yaml.ScalarNode):
continue
field = key_node.value.strip()
if field not in _CATALOG_FIELDS or field in fields:
continue
value = _normalize_frontmatter_value(field, value_node.value)
if value:
fields[field] = value
return fields
def _top_level_catalog_field(line: str) -> tuple[str, str] | None:
"""Split one top-level mapping line and decode its scalar key."""
if not line or line[0].isspace() or line[0] == "#":
return None
single_quoted = False
double_quoted = False
escaped = False
index = 0
while index < len(line):
char = line[index]
if double_quoted:
if escaped:
escaped = False
elif char == "\\":
escaped = True
elif char == '"':
double_quoted = False
elif single_quoted:
if char == "'" and index + 1 < len(line) and line[index + 1] == "'":
index += 1
elif char == "'":
single_quoted = False
elif char == "'":
single_quoted = True
elif char == '"':
double_quoted = True
elif char == ":":
field = _decode_scalar(line[:index])
if field in _CATALOG_FIELDS:
return field, line[index + 1 :]
return None
index += 1
return None
def _frontmatter_fields(lines: Sequence[str]) -> dict[str, str]:
fields = _structured_frontmatter_fields("".join(lines))
if "name" in fields and "description" in fields:
return fields
index = 0
while index < len(lines):
matched = _top_level_catalog_field(lines[index].rstrip("\r\n"))
if matched is None:
index += 1
continue
field, raw_value = matched
if field in fields:
index += 1
continue
value = _strip_yaml_comment(raw_value.strip())
if _BLOCK_SCALAR_RE.match(value):
continuation: list[str] = []
index += 1
while index < len(lines):
line = lines[index].rstrip("\r\n")
if line and not line[0].isspace() and _TOP_LEVEL_FIELD_RE.match(line):
break
continuation.append(line.strip())
index += 1
value = " ".join(part for part in continuation if part)
elif not value:
continuation = []
index += 1
while index < len(lines):
line = lines[index].rstrip("\r\n")
if line and not line[0].isspace():
if line.startswith("#"):
index += 1
continue
break
continuation.append(_strip_yaml_comment(line.strip()))
index += 1
value = " ".join(part for part in continuation if part)
elif value[0] in {"'", '"'} and not _quoted_scalar_is_closed(value):
continuation = [value]
index += 1
while index < len(lines):
line = lines[index].rstrip("\r\n")
if line and not line[0].isspace():
break
continuation.append(line.strip())
index += 1
combined = " ".join(part for part in continuation if part)
if _quoted_scalar_is_closed(combined):
break
value = _strip_yaml_comment(" ".join(part for part in continuation if part))
elif field == "description":
continuation = [value]
index += 1
while index < len(lines):
line = lines[index].rstrip("\r\n")
if line and not line[0].isspace():
break
continuation.append(_strip_yaml_comment(line.strip()))
index += 1
value = " ".join(part for part in continuation if part)
else:
index += 1
decoded = _normalize_frontmatter_value(field, _decode_scalar(value))
if decoded:
fields[field] = decoded
return fields
def _body_has_terminal_controls(value: str) -> bool:
return any(
unicodedata.category(char) == "Cc" and char not in {"\t", "\n", "\r"}
for char in value
)
def _stat_token(value: os.stat_result) -> tuple[int, int, int, int, int]:
return (
int(value.st_dev),
int(value.st_ino),
int(value.st_size),
int(getattr(value, "st_mtime_ns", int(value.st_mtime * 1_000_000_000))),
int(getattr(value, "st_ctime_ns", int(value.st_ctime * 1_000_000_000))),
)
def _directory_identity(value: os.stat_result) -> tuple[int, int]:
return int(value.st_dev), int(value.st_ino)
def _absolute_path(path: str | Path) -> Path:
return Path(os.path.abspath(os.path.expanduser(os.fspath(path))))
def _path_is_utf8(path: Path) -> bool:
try:
os.fspath(path).encode("utf-8", errors="strict")
except UnicodeEncodeError:
return False
return True
def _regular_open_flags() -> int:
flags = os.O_RDONLY
for name in ("O_BINARY", "O_CLOEXEC", "O_NONBLOCK", "O_NOFOLLOW"):
flags |= int(getattr(os, name, 0))
return flags
def _open_regular_file(path: str | Path, *, dir_fd: int | None = None) -> tuple[int, os.stat_result]:
raw_path = os.fspath(path)
follow_guard = int(getattr(os, "O_NOFOLLOW", 0))
before_path: os.stat_result | None = None
if not follow_guard:
try:
before_path = os.stat(raw_path, dir_fd=dir_fd, follow_symlinks=False)
except (OSError, TypeError, NotImplementedError):
before_path = None
if before_path is not None and not stat.S_ISREG(before_path.st_mode):
raise OSError(errno.EINVAL, "Skill file is not a regular file", raw_path)
try:
fd = os.open(raw_path, _regular_open_flags(), dir_fd=dir_fd)
except (TypeError, NotImplementedError):
if dir_fd is not None:
raise
fd = os.open(raw_path, _regular_open_flags())
try:
opened = os.fstat(fd)
if not stat.S_ISREG(opened.st_mode):
raise OSError(errno.EINVAL, "Skill file is not a regular file", raw_path)
if before_path is not None and _directory_identity(before_path) != _directory_identity(opened):
raise OSError(errno.ESTALE, "Skill file changed while opening", raw_path)
return fd, opened
except BaseException:
os.close(fd)
raise
def _frontmatter_bounds(data: bytes, *, complete: bool) -> tuple[int, int, int] | None:
start = 3 if data.startswith(b"\xef\xbb\xbf") else 0
opening_end = data.find(b"\n", start)
if opening_end < 0:
return None
if data[start:opening_end].rstrip(b"\r") != b"---":
return None
position = opening_end + 1
while position <= len(data):
line_end = data.find(b"\n", position)
if line_end < 0:
if not complete:
return None
line_end = len(data)
next_position = line_end
else:
next_position = line_end + 1
if data[position:line_end].rstrip(b"\r") == b"---":
return opening_end + 1, position, next_position
if line_end >= len(data):
return None
position = next_position
return None
def _read_prefix(fd: int, *, limit: int, file_size: int) -> bytes:
data = bytearray()
while len(data) < limit:
chunk = os.read(fd, min(4096, limit - len(data)))
if not chunk:
break
data.extend(chunk)
if _frontmatter_bounds(bytes(data), complete=len(data) >= file_size) is not None:
break
return bytes(data)
def _read_all(fd: int, *, limit: int) -> bytes:
data = bytearray()
while len(data) <= limit:
chunk = os.read(fd, min(64 * 1024, limit + 1 - len(data)))
if not chunk:
return bytes(data)
data.extend(chunk)
raise ValueError("Skill file exceeds the load limit")
def _read_skill_path(
skill_file: Path,
*,
priority: tuple[object, ...],
include_body: bool,
frontmatter_limit: int = FRONTMATTER_MAX_BYTES,
dir_fd: int | None = None,
source_directory: Path | None = None,
source_directory_identity: tuple[int, int] | None = None,
expected_directory_identity: tuple[int, int] | None = None,
) -> tuple[ManagedSkill | None, int]:
fd: int | None = None
try:
fd, before = _open_regular_file(
"SKILL.md" if dir_fd is not None else skill_file,
dir_fd=dir_fd,
)
if before.st_size > FRONTMATTER_MAX_BYTES + SKILL_BODY_MAX_BYTES:
return None, 0
if include_body:
data = _read_all(fd, limit=FRONTMATTER_MAX_BYTES + SKILL_BODY_MAX_BYTES)
else:
data = _read_prefix(
fd,
limit=min(FRONTMATTER_MAX_BYTES, max(0, frontmatter_limit)),
file_size=int(before.st_size),
)
after = os.fstat(fd)
if _stat_token(before) != _stat_token(after):
return None, len(data)
try:
path_after = os.stat(
"SKILL.md" if dir_fd is not None else skill_file,
dir_fd=dir_fd,
follow_symlinks=False,
)
except (OSError, TypeError, NotImplementedError):
return None, len(data)
if (
not stat.S_ISREG(path_after.st_mode)
or _directory_identity(path_after) != _directory_identity(before)
):
return None, len(data)
except (OSError, ValueError):
return None, 0
finally:
if fd is not None:
os.close(fd)
bounds = _frontmatter_bounds(data, complete=include_body or len(data) >= before.st_size)
if bounds is None:
return None, min(len(data), frontmatter_limit)
frontmatter_start, frontmatter_end, body_start = bounds
if body_start > FRONTMATTER_MAX_BYTES or body_start > frontmatter_limit:
return None, min(body_start, frontmatter_limit)
if before.st_size - body_start > SKILL_BODY_MAX_BYTES:
return None, body_start
frontmatter = data[frontmatter_start:frontmatter_end].decode("utf-8", errors="replace")
fields = _frontmatter_fields(frontmatter.splitlines(keepends=True))
name = fields.get("name", "")
description = fields.get("description", "")
disable_model_invocation = fields.get("disable-model-invocation", "").casefold() in {
"1",
"on",
"true",
"yes",
}
if not description or not 1 <= len(name) <= 64 or _PORTABLE_NAME_RE.fullmatch(name) is None:
return None, body_start
if len(description) > CATALOG_DESCRIPTION_MAX_CHARS:
description = description[: CATALOG_DESCRIPTION_MAX_CHARS - 3].rstrip() + "..."
body: str | None = None
if include_body:
try:
body = data[body_start:].decode("utf-8")
except UnicodeDecodeError:
return None, body_start
directory = _absolute_path(skill_file.parent)
if not _path_is_utf8(directory):
return None, body_start
source = _absolute_path(source_directory or directory)
try:
directory_stat = directory.stat(follow_symlinks=False)
except OSError:
return None, body_start
if not stat.S_ISDIR(directory_stat.st_mode):
return None, body_start
directory_identity = _directory_identity(directory_stat)
if expected_directory_identity is not None and directory_identity != expected_directory_identity:
return None, body_start
if not _source_directory_still_matches(
source,
directory,
source_directory_identity or directory_identity,
):
return None, body_start
return (
ManagedSkill(
name=name,
description=description,
directory=directory,
priority=priority,
body=body,
directory_identity=directory_identity,
source_directory=source,
source_directory_identity=source_directory_identity or directory_identity,
frontmatter_bytes=body_start,
disable_model_invocation=disable_model_invocation,
),
body_start,
)
def parse_skill_file(
skill_file: Path,
*,
priority: tuple[object, ...],
include_body: bool = True,
) -> ManagedSkill | None:
"""Parse one Skill through the same bounded regular-file path as discovery."""
normalized_priority = tuple(priority)
if len(normalized_priority) == 3:
normalized_priority = (*normalized_priority, str(_absolute_path(skill_file.parent)))
skill, _ = _read_skill_path(
skill_file,
priority=normalized_priority,
include_body=include_body,
)
return skill
def _dir_entry_stat(entry: os.DirEntry, *, follow_symlinks: bool = False) -> os.stat_result:
# DirEntry.stat() reports st_dev/st_ino as zero on Windows; identity and
# publication tokens need the path's real stat, same as discovery (#2270).
return os.stat(entry.path, follow_symlinks=follow_symlinks)
def _root_children(
root: Path,
*,
ignored_names: frozenset[str] = frozenset(),
budget: _DiscoveryBudget | None = None,
) -> list[tuple[str, Path, os.stat_result]] | None:
children: list[tuple[str, Path, os.stat_result]] = []
limit = DISCOVERY_ROOT_MAX_CHILDREN
if budget is not None:
if budget.remaining_children == 0:
return None
limit = min(limit, budget.remaining_children)
enumerated = 0
try:
with os.scandir(root) as entries:
for entry in entries:
enumerated += 1
if enumerated > limit:
if budget is not None:
budget.direct_children += enumerated
return None
if entry.name in ignored_names:
continue
try:
entry_stat = _dir_entry_stat(entry, follow_symlinks=False)
except OSError:
continue
children.append((entry.name, Path(entry.path), entry_stat))
except OSError:
return []
if budget is not None:
budget.direct_children += enumerated
children.sort(key=lambda item: item[0])
return children
def _resolved_candidate_directory(
source: Path,
source_stat: os.stat_result,
) -> tuple[Path, tuple[int, int], tuple[int, int]] | None:
source_identity = _directory_identity(source_stat)
if stat.S_ISDIR(source_stat.st_mode):
return _absolute_path(source), source_identity, source_identity
if not stat.S_ISLNK(source_stat.st_mode):
return None
try:
target = source.resolve(strict=True)
target_stat = target.stat(follow_symlinks=False)
after = source.stat(follow_symlinks=False)
except (OSError, RuntimeError):
return None
if (
not stat.S_ISDIR(target_stat.st_mode)
or not stat.S_ISLNK(after.st_mode)
or _directory_identity(after) != source_identity
):
return None
return _absolute_path(target), source_identity, _directory_identity(target_stat)
def _scan_root(
root: Path,
*,
priority: tuple[int, int, int],
budget: _DiscoveryBudget,
seen_directory_identities: set[tuple[int, int]] | None = None,
ignored_names: frozenset[str] = frozenset(),
skip_catalog_noise: bool = False,
) -> list[ManagedSkill]:
children = _root_children(root, ignored_names=ignored_names, budget=budget)
if children is None:
logger.info("Omitting oversized Skill root: %s", root)
return []
skills: list[ManagedSkill] = []
for name, child, child_stat in children:
if skip_catalog_noise and _is_catalog_noise(name, child):
continue
if budget.parse_exhausted:
break
resolved_directory = _resolved_candidate_directory(child, child_stat)
if resolved_directory is None:
continue
directory, source_identity, directory_identity = resolved_directory
if not _path_is_utf8(directory):
continue
if seen_directory_identities is not None:
if directory_identity in seen_directory_identities:
continue
seen_directory_identities.add(directory_identity)
budget.candidates += 1
skill_file = directory / "SKILL.md"
path_priority: tuple[object, ...] = (*priority, str(_absolute_path(child)))
skill, consumed = _read_skill_path(
skill_file,
priority=path_priority,
include_body=False,
frontmatter_limit=min(FRONTMATTER_MAX_BYTES, budget.remaining_frontmatter),
source_directory=child,
source_directory_identity=source_identity,
expected_directory_identity=directory_identity,
)
budget.frontmatter_bytes += consumed
if skill is not None:
skills.append(skill)
return skills
def _project_directories(
cwd: Path,
*,
project_base: str | Path | None = None,
) -> list[Path]:
current = cwd.expanduser().resolve()
if not current.is_dir():
return []
boundary = _project_base_for_working_directory(current, project_base)
directories: list[Path] = []
directory = current
for _ in range(PROJECT_ROOT_MAX_DIRECTORIES):
directories.append(directory)
if directory == boundary or (boundary is None and (directory / ".git").exists()):
return directories
if directory.parent == directory:
break
directory = directory.parent
return [current]
def _project_base_for_working_directory(
working_directory: Path,
project_base: str | Path | None,
) -> Path | None:
if project_base is None:
return None
raw = Path(project_base).expanduser()
if not raw.is_absolute():
return None
try:
resolved = raw.resolve()
except (OSError, RuntimeError):
return None
try:
relative = working_directory.relative_to(resolved)
except ValueError:
return None
if len(relative.parts) >= PROJECT_ROOT_MAX_DIRECTORIES:
return None
return resolved
def managed_skill_project_base(context: Any) -> str | None:
"""Return the project base bound to a resolved Avibe run target."""
payload = getattr(context, "platform_specific", None) or {}
target = payload.get("agent_run_target") if isinstance(payload, dict) else None
value = target.get("project_base") if isinstance(target, dict) else None
return str(value) if isinstance(value, str) and value else None
def _working_directory(cwd: str | Path | None) -> Path:
if cwd is not None:
return Path(cwd).expanduser().resolve()
bound = os.environ.get(SKILL_WORKING_DIR_ENV)
return Path(bound or Path.cwd()).expanduser().resolve()
def _selected_builtin_root(
avibe_home: Path,
*,
catalog_root: str | Path | None = None,
) -> Path | None:
if catalog_root is not None:
bound_root = catalog_root
if not bound_root:
return None
elif BUILTIN_SKILLS_ROOT_ENV in os.environ:
bound_root = os.environ.get(BUILTIN_SKILLS_ROOT_ENV)
if not bound_root:
return None
else:
bound_root = None
if bound_root:
raw_root = Path(bound_root).expanduser()
if not raw_root.is_absolute():
return None
return _existing_directory(_live_or_backup_catalog(_absolute_path(raw_root)))
root = avibe_home / "builtin-skills"
if not _readable_builtin_catalog(root):
try:
publish_builtin_skills(destination_root=root)
except Exception:
logger.warning("Failed to publish Avibe built-in Skills", exc_info=True)
return None
return _existing_directory(root)
def _existing_directory(path: Path) -> Path | None:
try:
value = path.stat(follow_symlinks=False)
except OSError:
return None
return path if stat.S_ISDIR(value.st_mode) else None
def _catalog_backup_path(destination: Path) -> Path:
return destination.parent / ".builtin-skills.previous"
def _catalog_staging_path(destination: Path) -> Path:
return destination.parent / ".builtin-skills.staging"
def _live_or_backup_catalog(root: Path) -> Path:
named = root
if (
_LEGACY_SNAPSHOT_ID_RE.fullmatch(root.name) is not None
and root.parent.name == "builtin-skills"
):
if _existing_directory(root) is not None:
return root
named = root.parent
if _readable_builtin_catalog(named):
return named
backup = _catalog_backup_path(named)
if _readable_builtin_catalog(backup):
return backup
return named
def _is_catalog_noise(name: str, child: Path) -> bool:
return name.startswith(".") or (
_LEGACY_SNAPSHOT_ID_RE.fullmatch(name) is not None
and not (child / "SKILL.md").is_file()
)
def _readable_builtin_catalog(root: Path) -> bool:
try:
root_stat = root.stat(follow_symlinks=False)
except OSError:
return False
if not stat.S_ISDIR(root_stat.st_mode):
return False
try:
with os.scandir(root) as scanned:
for entry in scanned:
child = Path(entry.path)
if _is_catalog_noise(entry.name, child):
continue
try:
child_stat = _dir_entry_stat(entry, follow_symlinks=False)
except OSError:
continue
if stat.S_ISDIR(child_stat.st_mode) and (child / "SKILL.md").is_file():
return True
except OSError:
return False
return False
def resolve_skills(
cwd: str | Path | None = None,
*,
project_base: str | Path | None = None,
home: str | Path | None = None,
avibe_home: str | Path | None = None,
codex_home: str | Path | None = None,
claude_home: str | Path | None = None,
xdg_config_home: str | Path | None = None,
builtin_catalog_root: str | Path | None = None,
) -> list[ManagedSkill]:
"""Resolve the live Skill catalog using Avibe's v1 precedence rules."""
resolved_home = (
Path(home).expanduser().resolve()
if home is not None
else Path(os.environ.get(SKILL_HOME_ENV) or Path.home()).expanduser().resolve()
)
resolved_avibe_home = (
Path(avibe_home).expanduser().resolve()
if avibe_home is not None
else paths.get_vibe_remote_dir().expanduser().resolve()
)
resolved_codex_home = (
Path(codex_home).expanduser().resolve()
if codex_home is not None
else Path(
os.environ.get(SKILL_CODEX_HOME_ENV)
or os.environ.get("CODEX_HOME")
or resolved_home / ".codex"
)
.expanduser()
.resolve()
)
if claude_home is not None:
resolved_claude_home = Path(claude_home).expanduser().resolve()
else:
bound_claude_home = os.environ.get(SKILL_CLAUDE_HOME_ENV)
if bound_claude_home:
resolved_claude_home = Path(bound_claude_home).expanduser().resolve()
else:
from vibe.claude_config import get_claude_home
resolved_claude_home = get_claude_home(resolved_home if home is not None else None).expanduser().resolve()
resolved_xdg_home = (
Path(xdg_config_home).expanduser().resolve()
if xdg_config_home is not None
else Path(
os.environ.get(SKILL_XDG_CONFIG_HOME_ENV)
or os.environ.get("XDG_CONFIG_HOME")
or resolved_home / ".config"
)
.expanduser()
.resolve()
)
candidates: list[ManagedSkill] = []
builtin_budget = _DiscoveryBudget()
builtin_root = _selected_builtin_root(
resolved_avibe_home,
catalog_root=builtin_catalog_root,
)
if builtin_root is not None:
candidates.extend(
_scan_root(
builtin_root,
priority=(0, 0, 0),
budget=builtin_budget,
skip_catalog_noise=True,
)
)
compatibility_budget = _DiscoveryBudget()
compatibility_directory_identities: set[tuple[int, int]] = set()
working_directory = _working_directory(cwd)
selected_project_base = (
project_base
if project_base is not None
else os.environ.get(SKILL_PROJECT_BASE_ENV)
)
for depth, directory in enumerate(
_project_directories(
working_directory,
project_base=selected_project_base,
)
):
for relative_root, family_rank in _PROJECT_FAMILIES:
if compatibility_budget.exhausted:
break
candidates.extend(
_scan_root(
directory / relative_root,
priority=(1, depth, family_rank),
budget=compatibility_budget,
seen_directory_identities=compatibility_directory_identities,
)
)
if compatibility_budget.exhausted:
break
global_user_roots = (
(resolved_home / ".agents" / "skills", 1, frozenset()),
(resolved_codex_home / "skills", 2, frozenset({".system"})),
(resolved_claude_home / "skills", 3, frozenset()),
(resolved_xdg_home / "opencode" / "skills", 4, frozenset()),
)
for root, family_rank, ignored_names in global_user_roots:
if compatibility_budget.exhausted:
break
candidates.extend(
_scan_root(
root,
priority=(2, 0, family_rank),
budget=compatibility_budget,
seen_directory_identities=compatibility_directory_identities,
ignored_names=ignored_names,
)
)
if not compatibility_budget.exhausted:
candidates.extend(
_scan_root(
resolved_codex_home / "skills" / ".system",
priority=(2, 0, 5),
budget=compatibility_budget,
seen_directory_identities=compatibility_directory_identities,
)
)
winners: dict[str, ManagedSkill] = {}
for candidate in candidates:
current = winners.get(candidate.name)
if current is None or candidate.priority < current.priority:
winners[candidate.name] = candidate
return sorted(winners.values(), key=lambda skill: skill.name)
def catalog_page_of(items: Sequence[T], row: Callable[[T], str], page: int) -> tuple[Sequence[T], int | None]:
"""One prompt catalog page: at most ``CATALOG_PAGE_SIZE`` rows and ``CATALOG_PAGE_MAX_BYTES``, never empty."""
if isinstance(page, bool) or page < 1:
raise ValueError("page must be a positive integer")
pages: list[list[T]] = []
current: list[T] = []
current_bytes = 0
for item in items:
line = row(item)
row_bytes = len(line.encode("utf-8")) + (1 if current else 0)
if current and (len(current) >= CATALOG_PAGE_SIZE or current_bytes + row_bytes > CATALOG_PAGE_MAX_BYTES):
pages.append(current)
current = []
current_bytes = 0
row_bytes = len(line.encode("utf-8"))
current.append(item)
current_bytes += row_bytes
if current:
pages.append(current)
if page > len(pages):
return (), None
return pages[page - 1], page + 1 if page < len(pages) else None
def catalog_page(skills: Sequence[ManagedSkill], page: int) -> tuple[Sequence[ManagedSkill], int | None]:
listed = sorted(
(skill for skill in skills if not skill.disable_model_invocation),
key=lambda item: (item.name.casefold(), item.name, item.description, str(item.directory)),
)
return catalog_page_of(listed, lambda skill: f"- {skill.name}: {skill.description}", page)
def _skill_list_rows(entries: Sequence[ManagedSkill]) -> list[str]:
return [f"- {skill.name}: {skill.description}" for skill in entries]
def render_skill_catalog_prompt(skills: Sequence[ManagedSkill]) -> str:
return join_prompt_blocks(render_skill_catalog_blocks(skills))
def render_skill_catalog_blocks(skills: Sequence[ManagedSkill]) -> list[RenderedPromptBlock]:
entries, next_page = catalog_page(skills, 1)
rows = "\n".join(_skill_list_rows(entries))
if not rows:
if any(skill.disable_model_invocation for skill in skills):
return [render_prompt_block("skills-manual-prompt")]
return []
blocks = [render_prompt_block("skills-prompt"), render_prompt_block("skills-catalog-heading")]
if next_page is not None:
blocks.append(render_prompt_block("skills-pagination-prompt"))
blocks.append(render_prompt_block("skills-catalog", skill_rows=rows))
if next_page is not None:
notice = render_prompt_block("skills-more-notice", next_page=next_page)
blocks.append(RenderedPromptBlock(notice.module_id, "\n" + notice.text))
return blocks
def render_skill_content(skill: ManagedSkill) -> str:
if skill.body is None:
raise ValueError("Skill body was not loaded")
name = html.escape(skill.name, quote=True)
directory = html.escape(str(skill.directory), quote=True)
directory = "".join(
f"&#x{ord(char):X};" if unicodedata.category(char).startswith("C") else char for char in directory
)
return f'<skill_content name="{name}" directory="{directory}">\n{skill.body}</skill_content>'
def _open_selected_directory(skill: ManagedSkill) -> tuple[int | None, tuple[int, int]]:
if not _source_directory_still_matches(
skill.source_directory or skill.directory,
skill.directory,
skill.source_directory_identity or skill.directory_identity,
):
raise OSError(errno.ESTALE, "Selected Skill source directory changed")
try:
before = skill.directory.stat(follow_symlinks=False)
except OSError as exc:
raise OSError(errno.ESTALE, "Selected Skill directory disappeared") from exc
if not stat.S_ISDIR(before.st_mode):
raise OSError(errno.ENOTDIR, "Selected Skill path is not a directory")
identity = _directory_identity(before)
if skill.directory_identity is not None and identity != skill.directory_identity:
raise OSError(errno.ESTALE, "Selected Skill directory changed")
flags = os.O_RDONLY
for name in ("O_CLOEXEC", "O_NONBLOCK", "O_NOFOLLOW", "O_DIRECTORY"):
flags |= int(getattr(os, name, 0))
try:
fd = os.open(skill.directory, flags)
except OSError:
if os.name != "nt":
raise
return None, identity
opened = os.fstat(fd)
if not stat.S_ISDIR(opened.st_mode) or _directory_identity(opened) != identity:
os.close(fd)
raise OSError(errno.ESTALE, "Selected Skill directory changed while opening")
return fd, identity
def _directory_path_still_matches(path: Path, identity: tuple[int, int]) -> bool:
try:
current = path.stat(follow_symlinks=False)
except OSError:
return False
return stat.S_ISDIR(current.st_mode) and _directory_identity(current) == identity
def _source_directory_still_matches(
source: Path,
target: Path,
identity: tuple[int, int] | None,
) -> bool:
try:
before = source.stat(follow_symlinks=False)
if identity is not None and _directory_identity(before) != identity:
return False
if source == target:
return stat.S_ISDIR(before.st_mode)
if not stat.S_ISLNK(before.st_mode):
return False
resolved = source.resolve(strict=True)
after = source.stat(follow_symlinks=False)
except (OSError, RuntimeError):
return False
return (
resolved == target and stat.S_ISLNK(after.st_mode) and _directory_identity(after) == _directory_identity(before)
)
def is_skill_name(name: str) -> bool:
"""Whether ``name`` is one ``load_skill`` can load: portable, at most 64 characters."""
return 1 <= len(name) <= 64 and _PORTABLE_NAME_RE.fullmatch(name) is not None
def load_skill(
name: str,
cwd: str | Path | None = None,
*,
resolved_skills: Sequence[ManagedSkill] | None = None,
) -> ManagedSkill | None:
if not is_skill_name(name):
return None
catalog = resolve_skills(cwd) if resolved_skills is None else resolved_skills
winner = next((skill for skill in catalog if skill.name == name), None)
if winner is None:
return None
directory_fd: int | None = None
try:
directory_fd, identity = _open_selected_directory(winner)
loaded, _ = _read_skill_path(
winner.directory / "SKILL.md",
priority=winner.priority,
include_body=True,
dir_fd=directory_fd,
)
if (
loaded is None
or loaded.name != name
or loaded.body is None
or _body_has_terminal_controls(loaded.body)
):
return None
if not _directory_path_still_matches(winner.directory, identity) or not _source_directory_still_matches(
winner.source_directory or winner.directory,
winner.directory,
winner.source_directory_identity or identity,
):
return None
return ManagedSkill(
name=loaded.name,
description=loaded.description,
directory=winner.directory,
priority=winner.priority,
body=loaded.body,
directory_identity=identity,
source_directory=winner.source_directory,
source_directory_identity=winner.source_directory_identity,
frontmatter_bytes=loaded.frontmatter_bytes,
disable_model_invocation=loaded.disable_model_invocation,
)
except OSError:
return None
finally:
if directory_fd is not None:
os.close(directory_fd)
def builtin_skills_source() -> Path:
checkout_root = Path(__file__).resolve().parents[1]
checkout_source = checkout_root / "skills"
pyproject = checkout_root / "pyproject.toml"
pyproject_fd: int | None = None
try:
pyproject_fd, _ = _open_regular_file(pyproject)
project_header = _read_all(pyproject_fd, limit=64 * 1024)
project_metadata = tomllib.loads(project_header.decode("utf-8"))
project_name = str(project_metadata.get("project", {}).get("name") or "")
except (OSError, UnicodeDecodeError, ValueError):
project_name = ""
finally:
if pyproject_fd is not None:
os.close(pyproject_fd)
if checkout_source.is_dir() and (checkout_root / "vibe" / "__init__.py").is_file() and project_name == "avibe-os":
return checkout_source
import vibe
packaged_source = Path(vibe.__file__).resolve().parent / "builtin_skills_source"
if packaged_source.is_dir():
return packaged_source
raise RuntimeError("Avibe built-in Skills are missing from this installation")
def _validate_portable_component(component: str) -> None:
if not component or component in {".", ".."}:
raise RuntimeError("Built-in Skill paths must be relative")
if unicodedata.normalize("NFC", component) != component:
raise RuntimeError(f"Built-in Skill path is not NFC: {component!r}")
if component[-1] in {".", " "}:
raise RuntimeError(f"Built-in Skill path has a trailing dot or space: {component!r}")
if any(ord(char) < 32 or char in _WINDOWS_INVALID_CHARS or char == "\x00" for char in component):
raise RuntimeError(f"Built-in Skill path is not portable: {component!r}")
basename = component.split(".", 1)[0].casefold()
if basename in _WINDOWS_RESERVED:
raise RuntimeError(f"Built-in Skill path uses a Windows-reserved name: {component!r}")
def _snapshot_entries(root: Path) -> list[_SnapshotEntry]:
entries: list[_SnapshotEntry] = []
aliases: set[str] = set()
file_bytes = 0
pending: list[tuple[Path, tuple[str, ...]]] = [(root, ())]
while pending:
directory, relative_parts = pending.pop()
try:
with os.scandir(directory) as scanned:
children = sorted(scanned, key=lambda item: item.name)
except OSError as exc:
raise RuntimeError(f"Cannot read built-in Skill source: {directory}") from exc
accepted_children = 0
child_directories: list[tuple[Path, tuple[str, ...]]] = []
for child in children:
# Installers may compile Skill scripts in place; bytecode is not part of the bundled tree.
if child.name == "__pycache__" or child.name.endswith(_GENERATED_BYTECODE_SUFFIXES):
continue
accepted_children += 1
_validate_portable_component(child.name)
child_parts = (*relative_parts, child.name)
relative = "/".join(child_parts)
relative_bytes = relative.encode("utf-8")
alias = relative.casefold()
if alias in aliases:
raise RuntimeError(f"Built-in Skill paths collide case-insensitively: {relative}")
aliases.add(alias)
if len(entries) >= BUILTIN_TREE_MAX_ENTRIES:
raise RuntimeError(
f"Built-in Skill tree exceeds {BUILTIN_TREE_MAX_ENTRIES:,} entries"
)
try:
child_stat = _dir_entry_stat(child, follow_symlinks=False)
except OSError as exc:
raise RuntimeError(f"Cannot inspect built-in Skill path: {relative}") from exc
file_attributes = int(getattr(child_stat, "st_file_attributes", 0))
reparse_flag = int(getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0))
if reparse_flag and file_attributes & reparse_flag:
raise RuntimeError(f"Built-in Skill path is a reparse point: {relative}")
token = _stat_token(child_stat)
if stat.S_ISDIR(child_stat.st_mode):
entries.append(
_SnapshotEntry(Path(child.path), relative, relative_bytes, True, token)
)
child_directories.append((Path(child.path), child_parts))
elif stat.S_ISREG(child_stat.st_mode):
file_bytes += int(child_stat.st_size)
if file_bytes > BUILTIN_TREE_MAX_BYTES:
raise RuntimeError(
f"Built-in Skill tree exceeds {BUILTIN_TREE_MAX_BYTES:,} bytes"
)
entries.append(
_SnapshotEntry(Path(child.path), relative, relative_bytes, False, token)
)
else:
raise RuntimeError(f"Built-in Skill path is not a directory or regular file: {relative}")
if relative_parts and accepted_children == 0:
raise RuntimeError(f"Built-in Skill directories must not be empty: {'/'.join(relative_parts)}")
pending.extend(reversed(child_directories))
entries.sort(key=lambda entry: entry.relative_bytes)
return entries
def _copy_snapshot_entries(entries: Sequence[_SnapshotEntry], destination: Path) -> None:
"""Copy one pre-enumerated tree while charging bytes actually opened."""
consumed_bytes = 0
for entry in entries:
target = destination.joinpath(*entry.relative.split("/"))
if entry.is_directory:
try:
source_stat = entry.path.stat(follow_symlinks=False)
except OSError as exc:
raise RuntimeError(
f"Cannot inspect built-in Skill path: {entry.relative}"
) from exc
if not stat.S_ISDIR(source_stat.st_mode):
raise RuntimeError(
f"Built-in Skill directory changed during publication: {entry.relative}"
)
target.mkdir(mode=0o700)
continue
source_fd: int | None = None
target_fd: int | None = None
try:
source_fd, before = _open_regular_file(entry.path)
file_size = int(before.st_size)
if file_size > BUILTIN_TREE_MAX_BYTES - consumed_bytes:
raise RuntimeError(
f"Built-in Skill tree exceeds {BUILTIN_TREE_MAX_BYTES:,} bytes"
)
consumed_bytes += file_size
target_flags = (
os.O_WRONLY
| os.O_CREAT
| os.O_EXCL
| getattr(os, "O_BINARY", 0)
)
target_fd = os.open(target, target_flags, 0o600)
remaining = file_size
while remaining:
chunk = os.read(source_fd, min(1024 * 1024, remaining))
if not chunk:
raise RuntimeError(
f"Built-in Skill file changed during publication: {entry.relative}"
)
view = memoryview(chunk)
while view:
written = os.write(target_fd, view)
view = view[written:]
remaining -= len(chunk)
if os.read(source_fd, 1):
raise RuntimeError(
f"Built-in Skill file grew during publication: {entry.relative}"
)
after = os.fstat(source_fd)
if _stat_token(before) != _stat_token(after):
raise RuntimeError(
f"Built-in Skill file changed during publication: {entry.relative}"
)
if os.name != "nt" and callable(getattr(os, "fchmod", None)):
os.fchmod(target_fd, 0o644 | int(before.st_mode & 0o111))
finally:
if target_fd is not None:
os.close(target_fd)
if source_fd is not None:
os.close(source_fd)
def _validate_builtin_catalog(root: Path) -> None:
children = _root_children(root)
if children is None:
raise RuntimeError("Avibe packages at most 1,024 built-in Skills")
frontmatter_bytes = 0
declared_names: set[str] = set()
for name, child, child_stat in children:
if not stat.S_ISDIR(child_stat.st_mode):
raise RuntimeError(f"Built-in Skill root entry is not a directory: {name}")
skill, consumed = _read_skill_path(
child / "SKILL.md",
priority=(0, 0, 0, str(_absolute_path(child))),
include_body=True,
)
if skill is None:
raise RuntimeError(f"Built-in Skill is invalid: {name}")
if skill.name in declared_names:
raise RuntimeError(f"Built-in Skills must have unique declared names: {skill.name}")
declared_names.add(skill.name)
frontmatter_bytes += consumed
if frontmatter_bytes > DISCOVERY_CLASS_MAX_FRONTMATTER_BYTES:
raise RuntimeError("Built-in Skill frontmatter exceeds the 8 MiB catalog budget")
def _source_manifest(entries: Sequence[_SnapshotEntry]) -> tuple[tuple[bytes, bool, tuple[int, int, int, int, int]], ...]:
return tuple((entry.relative_bytes, entry.is_directory, entry.token) for entry in entries)
def _assert_source_unchanged(source: Path, entries: Sequence[_SnapshotEntry], snapshot: Path) -> None:
"""Recheck the validated copy's bytes, not just timestamp-based identities."""
for entry in entries:
if entry.is_directory:
continue
source_fd: int | None = None
snapshot_fd: int | None = None
changed = f"Built-in Skill source changed during publication: {entry.relative}"
try:
source_fd, before = _open_regular_file(entry.path)
snapshot_fd, copied = _open_regular_file(snapshot.joinpath(*entry.relative.split("/")))
# Windows/Python may give path stat and fstat different ctime meanings.
# Compare identity/size across APIs; compare timestamps within each API.
if (
_directory_identity(before) != entry.token[:2]
or before.st_size != entry.token[2]
or copied.st_size != before.st_size
):
raise RuntimeError(changed)
# Buffered binary reads handle short reads without comparing different
# chunk boundaries. Bound the work by the already-enumerated file size.
with os.fdopen(source_fd, "rb", closefd=False) as current, os.fdopen(
snapshot_fd, "rb", closefd=False
) as staged:
remaining = int(before.st_size)
while remaining:
chunk = current.read(min(1024 * 1024, remaining))
if not chunk or chunk != staged.read(len(chunk)):
raise RuntimeError(changed)
remaining -= len(chunk)
if current.read(1) or staged.read(1):
raise RuntimeError(changed)
if _stat_token(os.fstat(source_fd)) != _stat_token(before):
raise RuntimeError(changed)
except OSError as exc:
raise RuntimeError(changed) from exc
finally:
if snapshot_fd is not None:
os.close(snapshot_fd)
if source_fd is not None:
os.close(source_fd)
# Retain the tree/identity checks, including replacement or disappearance
# during the byte comparison. Stat tokens alone cannot detect same-tick writes.
if _source_manifest(_snapshot_entries(source)) != _source_manifest(entries):
raise RuntimeError("Built-in Skill source changed during publication")
def _remove_snapshot_staging(path: Path) -> None:
try:
value = path.lstat()
except FileNotFoundError:
return
except OSError as exc:
raise RuntimeError(f"Cannot inspect built-in Skill staging path: {path}") from exc
reparse_flag = int(getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0))
file_attributes = int(getattr(value, "st_file_attributes", 0))
if stat.S_ISLNK(value.st_mode) or (reparse_flag and file_attributes & reparse_flag):
if stat.S_ISDIR(value.st_mode):
path.rmdir()
else:
path.unlink()
return
if not stat.S_ISDIR(value.st_mode):
path.unlink()
return
try:
children = os.listdir(path)
except OSError as exc:
raise RuntimeError(f"Cannot inspect built-in Skill staging path: {path}") from exc
for name in children:
_remove_snapshot_staging(path / name)
path.rmdir()
def publish_builtin_skills(
*,
source_root: str | Path | None = None,
destination_root: str | Path | None = None,
) -> Path:
"""Publish this artifact's built-ins by replacing the live named catalog."""
source = Path(source_root).resolve() if source_root is not None else builtin_skills_source()
destination = (
Path(destination_root).expanduser().resolve()
if destination_root is not None
else (paths.get_vibe_remote_dir() / "builtin-skills").expanduser().resolve()
)
_validate_builtin_catalog(source)
entries = _snapshot_entries(source)
from storage.lock import MigrationFileLock
destination.parent.mkdir(parents=True, exist_ok=True)
lock_path = destination.parent / ".publish-builtin-skills.lock"
with MigrationFileLock(lock_path, timeout_seconds=None):
staging = _catalog_staging_path(destination)
backup = _catalog_backup_path(destination)
_remove_snapshot_staging(staging)
staging.mkdir(mode=0o700)
try:
_copy_snapshot_entries(entries, staging)
_validate_builtin_catalog(staging)
_assert_source_unchanged(source, entries, staging)
if os.path.lexists(destination):
try:
destination_stat = destination.stat(follow_symlinks=False)
except OSError as exc:
raise RuntimeError(f"Built-in Skill catalog is unavailable: {destination}") from exc
if not stat.S_ISDIR(destination_stat.st_mode):
raise RuntimeError(f"Built-in Skill catalog is not a directory: {destination}")
_remove_snapshot_staging(backup)
os.rename(destination, backup)
try:
os.rename(staging, destination)
except OSError:
if os.path.lexists(backup) and not os.path.lexists(destination):
os.rename(backup, destination)
raise
finally:
if os.path.lexists(staging):
_remove_snapshot_staging(staging)
return destination
def prepare_builtin_skills() -> Path:
"""Publish and bind the running artifact's live built-in catalog."""
try:
catalog = publish_builtin_skills()
except Exception:
os.environ.pop(BUILTIN_SKILLS_SNAPSHOT_ENV, None)
os.environ[BUILTIN_SKILLS_ROOT_ENV] = ""
raise
os.environ.pop(BUILTIN_SKILLS_SNAPSHOT_ENV, None)
os.environ[BUILTIN_SKILLS_ROOT_ENV] = str(catalog.expanduser().resolve())
return catalog
def managed_skill_environment(
working_directory: str | Path | None,
*,
project_base: str | Path | None = None,
builtin_catalog_root: str | Path | None = None,
) -> dict[str, str]:
"""Return the per-backend shell bindings consumed by ``vibe skill``."""
env: dict[str, str] = {}
if working_directory is not None:
resolved_working_directory = Path(working_directory).expanduser().resolve()
env[SKILL_WORKING_DIR_ENV] = str(resolved_working_directory)
resolved_project_base = _project_base_for_working_directory(
resolved_working_directory,
project_base,
)
if resolved_project_base is not None:
env[SKILL_PROJECT_BASE_ENV] = str(resolved_project_base)
resolved_home = Path.home().resolve()
resolved_codex_home = Path(os.environ.get("CODEX_HOME") or resolved_home / ".codex").expanduser().resolve()
from vibe.claude_config import get_claude_home
resolved_claude_home = get_claude_home().expanduser().resolve()
resolved_xdg_home = Path(os.environ.get("XDG_CONFIG_HOME") or resolved_home / ".config").expanduser().resolve()
env.update(
{
SKILL_HOME_ENV: str(resolved_home),
SKILL_CODEX_HOME_ENV: str(resolved_codex_home),
SKILL_CLAUDE_HOME_ENV: str(resolved_claude_home),
SKILL_XDG_CONFIG_HOME_ENV: str(resolved_xdg_home),
}
)
if builtin_catalog_root is not None:
bound_root = builtin_catalog_root
elif BUILTIN_SKILLS_ROOT_ENV in os.environ:
bound_root = os.environ.get(BUILTIN_SKILLS_ROOT_ENV)
else:
bound_root = None
if bound_root:
root = Path(bound_root).expanduser()
if root.is_absolute():
env[BUILTIN_SKILLS_ROOT_ENV] = str(_absolute_path(root))
else:
logger.warning("Ignoring invalid built-in Skill catalog root: %s", bound_root)
env[BUILTIN_SKILLS_ROOT_ENV] = ""
elif builtin_catalog_root is not None or BUILTIN_SKILLS_ROOT_ENV in os.environ:
env[BUILTIN_SKILLS_ROOT_ENV] = ""
else:
env[BUILTIN_SKILLS_ROOT_ENV] = str(
(paths.get_vibe_remote_dir() / "builtin-skills").expanduser().resolve()
)
return env