klaude-code 1.2.21__py3-none-any.whl → 1.2.23__py3-none-any.whl

klaude_code/{core/tool/memory/skill_loader.py → skill/loader.py}

@@ -15,12 +15,22 @@ class Skill:
     name: str  # Skill identifier (lowercase-hyphen)
     description: str  # What the skill does and when to use it
     content: str  # Full markdown instructions
-    location: str  # Skill location: 'user' or 'project'
+    location: str  # Skill location: 'system', 'user', or 'project'
     license: str | None = None
     allowed_tools: list[str] | None = None
     metadata: dict[str, str] | None = None
     skill_path: Path | None = None
 
+    @property
+    def short_description(self) -> str:
+        """Get short description for display in completions.
+
+        Returns metadata['short-description'] if available, otherwise falls back to description.
+        """
+        if self.metadata and "short-description" in self.metadata:
+            return self.metadata["short-description"]
+        return self.description
+
     def to_prompt(self) -> str:
         """Convert skill to prompt format for agent consumption"""
         return f"""# Skill: {self.name}
@@ -36,13 +46,15 @@ class Skill:
 class SkillLoader:
     """Load and manage Claude Skills from SKILL.md files"""
 
+    # System-level skills directory (built-in, lowest priority)
+    SYSTEM_SKILLS_DIR: ClassVar[Path] = Path("~/.klaude/skills/.system")
+
     # User-level skills directories (checked in order, later ones override earlier ones with same name)
     USER_SKILLS_DIRS: ClassVar[list[Path]] = [
         Path("~/.claude/skills"),
         Path("~/.klaude/skills"),
-        # Path("~/.claude/plugins/marketplaces"),
     ]
-    # Project-level skills directory
+    # Project-level skills directory (highest priority)
     PROJECT_SKILLS_DIR: ClassVar[Path] = Path("./.claude/skills")
 
     def __init__(self) -> None:
@@ -54,7 +66,7 @@ class SkillLoader:
 
         Args:
             skill_path: Path to SKILL.md file
-            location: Skill location ('user' or 'project')
+            location: Skill location ('system', 'user', or 'project')
 
         Returns:
             Skill object or None if loading failed
@@ -121,39 +133,57 @@ class SkillLoader:
             return None
 
     def discover_skills(self) -> list[Skill]:
-        """Recursively find all SKILL.md files and load them from both user and project directories
+        """Recursively find all SKILL.md files and load them from system, user and project directories.
+
+        Loading order (lower priority first, higher priority overrides):
+        1. System skills (~/.klaude/skills/.system/) - built-in, lowest priority
+        2. User skills (~/.claude/skills/, ~/.klaude/skills/) - user-level
+        3. Project skills (./.claude/skills/) - project-level, highest priority
 
         Returns:
             List of successfully loaded Skill objects
         """
         skills: list[Skill] = []
 
-        # Load user-level skills from all directories
+        # Load system-level skills first (lowest priority, can be overridden)
+        system_dir = self.SYSTEM_SKILLS_DIR.expanduser()
+        if system_dir.exists():
+            for skill_file in system_dir.rglob("SKILL.md"):
+                skill = self.load_skill(skill_file, location="system")
+                if skill:
+                    skills.append(skill)
+                    self.loaded_skills[skill.name] = skill
+
+        # Load user-level skills (override system skills if same name)
         for user_dir in self.USER_SKILLS_DIRS:
             expanded_dir = user_dir.expanduser()
             if expanded_dir.exists():
-                for pattern in ("SKILL.md", "skill.md"):
-                    for skill_file in expanded_dir.rglob(pattern):
-                        skill = self.load_skill(skill_file, location="user")
-                        if skill:
-                            skills.append(skill)
-                            self.loaded_skills[skill.name] = skill
+                for skill_file in expanded_dir.rglob("SKILL.md"):
+                    # Skip files under .system directory (already loaded above)
+                    if ".system" in skill_file.parts:
+                        continue
+                    skill = self.load_skill(skill_file, location="user")
+                    if skill:
+                        skills.append(skill)
+                        self.loaded_skills[skill.name] = skill
 
         # Load project-level skills (override user skills if same name)
         project_dir = self.PROJECT_SKILLS_DIR.resolve()
         if project_dir.exists():
-            for pattern in ("SKILL.md", "skill.md"):
-                for skill_file in project_dir.rglob(pattern):
-                    skill = self.load_skill(skill_file, location="project")
-                    if skill:
-                        skills.append(skill)
-                        self.loaded_skills[skill.name] = skill
+            for skill_file in project_dir.rglob("SKILL.md"):
+                skill = self.load_skill(skill_file, location="project")
+                if skill:
+                    skills.append(skill)
+                    self.loaded_skills[skill.name] = skill
 
         # Log discovery summary
         if skills:
+            system_count = sum(1 for s in skills if s.location == "system")
             user_count = sum(1 for s in skills if s.location == "user")
             project_count = sum(1 for s in skills if s.location == "project")
             parts: list[str] = []
+            if system_count > 0:
+                parts.append(f"{system_count} system")
             if user_count > 0:
                 parts.append(f"{user_count} user")
             if project_count > 0:
@@ -171,11 +201,17 @@ class SkillLoader:
         Returns:
             Skill object or None if not found
         """
+        # Prefer exact match first (supports namespaced skill names).
+        skill = self.loaded_skills.get(name)
+        if skill is not None:
+            return skill
+
         # Support both formats: 'pdf' and 'document-skills:pdf'
         if ":" in name:
-            name = name.split(":")[-1]
+            short = name.split(":")[-1]
+            return self.loaded_skills.get(short)
 
-        return self.loaded_skills.get(name)
+        return None
 
     def list_skills(self) -> list[str]:
         """Get list of all loaded skill names"""
@@ -224,25 +260,25 @@ class SkillLoader:
         content = re.sub(dir_pattern, replace_dir_path, content)
 
         # Pattern 2: Markdown links [text](./path or path)
-        # e.g., "[Guide](./docs/guide.md)" -> "[Guide](`/abs/path/to/docs/guide.md`) (use read_file to access)"
+        # e.g., "[Guide](./docs/guide.md)" -> "[Guide](`/abs/path/to/docs/guide.md`) (use the Read tool to access)"
         link_pattern = r"\[([^\]]+)\]\((\./)?([^\)]+\.md)\)"
 
         def replace_link(match: re.Match[str]) -> str:
             text = match.group(1)
             filename = match.group(3)
             abs_path = skill_dir / filename
-            return f"[{text}](`{abs_path}`) (use read_file to access)"
+            return f"[{text}](`{abs_path}`) (use the Read tool to access)"
 
         content = re.sub(link_pattern, replace_link, content)
 
         # Pattern 3: Standalone markdown references
-        # e.g., "see reference.md" -> "see `/abs/path/to/reference.md` (use read_file to access)"
+        # e.g., "see reference.md" -> "see `/abs/path/to/reference.md` (use the Read tool to access)"
         standalone_pattern = r"(?<!\])\b(\w+\.md)\b(?!\))"
 
         def replace_standalone(match: re.Match[str]) -> str:
             filename = match.group(1)
             abs_path = skill_dir / filename
-            return f"`{abs_path}` (use read_file to access)"
+            return f"`{abs_path}` (use the Read tool to access)"
 
         content = re.sub(standalone_pattern, replace_standalone, content)
 

klaude_code/skill/manager.py

@@ -0,0 +1,70 @@
+"""Global skill manager with lazy initialization.
+
+This module provides a centralized interface for accessing skills throughout the application.
+Skills are loaded lazily on first access to avoid unnecessary IO at startup.
+"""
+
+from klaude_code.skill.loader import Skill, SkillLoader
+from klaude_code.skill.system_skills import install_system_skills
+
+_loader: SkillLoader | None = None
+_initialized: bool = False
+
+
+def _ensure_initialized() -> SkillLoader:
+    """Ensure the skill system is initialized and return the loader."""
+    global _loader, _initialized
+    if not _initialized:
+        install_system_skills()
+        _loader = SkillLoader()
+        _loader.discover_skills()
+        _initialized = True
+    assert _loader is not None
+    return _loader
+
+
+def get_skill_loader() -> SkillLoader:
+    """Get the global skill loader instance.
+
+    Lazily initializes the skill system on first call.
+
+    Returns:
+        The global SkillLoader instance
+    """
+    return _ensure_initialized()
+
+
+def get_skill(name: str) -> Skill | None:
+    """Get a skill by name.
+
+    Args:
+        name: Skill name (supports both 'skill-name' and 'namespace:skill-name')
+
+    Returns:
+        Skill object or None if not found
+    """
+    return _ensure_initialized().get_skill(name)
+
+
+def get_available_skills() -> list[tuple[str, str, str]]:
+    """Get list of available skills for completion and display.
+
+    Returns:
+        List of (name, short_description, location) tuples.
+        Uses metadata['short-description'] if available, otherwise falls back to description.
+        Skills are ordered by priority: project > user > system.
+    """
+    loader = _ensure_initialized()
+    skills = [(s.name, s.short_description, s.location) for s in loader.loaded_skills.values()]
+    location_order = {"project": 0, "user": 1, "system": 2}
+    skills.sort(key=lambda x: location_order.get(x[2], 3))
+    return skills
+
+
+def list_skill_names() -> list[str]:
+    """Get list of all loaded skill names.
+
+    Returns:
+        List of skill names
+    """
+    return _ensure_initialized().list_skills()

klaude_code/skill/system_skills.py

@@ -0,0 +1,192 @@
+"""System skills management - install built-in skills to user directory.
+
+This module handles extracting bundled skills from the package to ~/.klaude/skills/.system/
+on application startup. It uses a fingerprint mechanism to avoid unnecessary re-extraction.
+"""
+
+import hashlib
+import shutil
+from collections.abc import Iterator
+from contextlib import contextmanager
+from importlib import resources
+from pathlib import Path
+
+from klaude_code.trace import log_debug
+
+# Marker file name for tracking installed skills version
+SYSTEM_SKILLS_MARKER_FILENAME = ".klaude-system-skills.marker"
+
+# Salt for fingerprint calculation (increment to force re-extraction)
+SYSTEM_SKILLS_MARKER_SALT = "v1"
+
+
+def get_system_skills_dir() -> Path:
+    """Get the system skills installation directory.
+
+    Returns:
+        Path to ~/.klaude/skills/.system/
+    """
+    return Path.home() / ".klaude" / "skills" / ".system"
+
+
+def _calculate_fingerprint(assets_dir: Path) -> str:
+    """Calculate a fingerprint hash for the embedded skills assets.
+
+    The fingerprint is based on all file paths and their contents.
+
+    Args:
+        assets_dir: Path to the assets directory
+
+    Returns:
+        Hex string of the hash
+    """
+    hasher = hashlib.sha256()
+    hasher.update(SYSTEM_SKILLS_MARKER_SALT.encode())
+
+    if not assets_dir.exists():
+        return hasher.hexdigest()
+
+    # Sort entries for consistent ordering
+    for entry in sorted(assets_dir.rglob("*")):
+        if entry.is_file():
+            # Hash the relative path
+            rel_path = entry.relative_to(assets_dir)
+            hasher.update(str(rel_path).encode())
+            # Hash the file contents
+            hasher.update(entry.read_bytes())
+
+    return hasher.hexdigest()
+
+
+def _read_marker(marker_path: Path) -> str | None:
+    """Read the fingerprint from the marker file.
+
+    Args:
+        marker_path: Path to the marker file
+
+    Returns:
+        The stored fingerprint, or None if the file doesn't exist or is invalid
+    """
+    try:
+        if marker_path.exists():
+            return marker_path.read_text(encoding="utf-8").strip()
+    except OSError:
+        pass
+    return None
+
+
+def _write_marker(marker_path: Path, fingerprint: str) -> None:
+    """Write the fingerprint to the marker file.
+
+    Args:
+        marker_path: Path to the marker file
+        fingerprint: The fingerprint to store
+    """
+    marker_path.write_text(f"{fingerprint}\n", encoding="utf-8")
+
+
+@contextmanager
+def _with_embedded_assets_dir() -> Iterator[Path | None]:
+    """Resolve the embedded assets directory as a real filesystem path.
+
+    Uses `importlib.resources.as_file()` so it works for both normal installs
+    and zipimport-style environments.
+    """
+    try:
+        assets_ref = resources.files("klaude_code.skill").joinpath("assets")
+        with resources.as_file(assets_ref) as assets_path:
+            p = Path(assets_path)
+            yield p if p.exists() else None
+            return
+    except (TypeError, AttributeError, ImportError, FileNotFoundError, OSError):
+        pass
+
+    try:
+        module_dir = Path(__file__).parent
+        assets_path = module_dir / "assets"
+        yield assets_path if assets_path.exists() else None
+    except (TypeError, NameError, OSError):
+        yield None
+
+
+def install_system_skills() -> bool:
+    """Install system skills from the embedded assets to the user directory.
+
+    This function:
+    1. Calculates a fingerprint of the embedded assets
+    2. Checks if the installed skills match (via marker file)
+    3. If they don't match, clears and re-extracts the skills
+
+    Returns:
+        True if skills were installed/updated, False if already up-to-date
+    """
+    dest_dir = get_system_skills_dir()
+    marker_path = dest_dir / SYSTEM_SKILLS_MARKER_FILENAME
+
+    with _with_embedded_assets_dir() as assets_path:
+        if assets_path is None or not assets_path.exists():
+            log_debug("No embedded system skills found")
+            return False
+
+        # Calculate fingerprint of embedded assets
+        expected_fingerprint = _calculate_fingerprint(assets_path)
+
+        # Check if already installed with matching fingerprint
+        current_fingerprint = _read_marker(marker_path)
+        if current_fingerprint == expected_fingerprint and dest_dir.exists():
+            log_debug("System skills already up-to-date")
+            return False
+
+        log_debug(f"Installing system skills to {dest_dir}")
+
+        # Clear existing installation
+        if dest_dir.exists():
+            try:
+                shutil.rmtree(dest_dir)
+            except OSError as e:
+                log_debug(f"Failed to clear existing system skills: {e}")
+                return False
+
+        # Create destination directory
+        dest_dir.mkdir(parents=True, exist_ok=True)
+
+        # Copy all skill directories from assets
+        try:
+            for item in assets_path.iterdir():
+                if item.is_dir() and not item.name.startswith("."):
+                    dest_skill_dir = dest_dir / item.name
+                    shutil.copytree(item, dest_skill_dir)
+                    log_debug(f"Installed system skill: {item.name}")
+        except OSError as e:
+            log_debug(f"Failed to copy system skills: {e}")
+            return False
+
+        # Write marker file
+        try:
+            _write_marker(marker_path, expected_fingerprint)
+        except OSError as e:
+            log_debug(f"Failed to write marker file: {e}")
+            # Installation succeeded, just marker failed
+
+        log_debug("System skills installation complete")
+        return True
+
+
+def get_installed_system_skills() -> list[Path]:
+    """Get list of installed system skill directories.
+
+    Returns:
+        List of paths to installed skill directories
+    """
+    dest_dir = get_system_skills_dir()
+    if not dest_dir.exists():
+        return []
+
+    skills: list[Path] = []
+    for item in dest_dir.iterdir():
+        if item.is_dir() and not item.name.startswith("."):
+            skill_file = item / "SKILL.md"
+            if skill_file.exists():
+                skills.append(item)
+
+    return skills

klaude_code/ui/modes/repl/completers.py

@@ -1,13 +1,15 @@
-"""REPL completion handlers for @ file paths and / slash commands.
+"""REPL completion handlers for @ file paths, / slash commands, and $ skills.
 
 This module provides completers for the REPL input:
 - _SlashCommandCompleter: Completes slash commands on the first line
+- _SkillCompleter: Completes skill names on the first line with $ prefix
 - _AtFilesCompleter: Completes @path segments using fd or ripgrep
-- _ComboCompleter: Combines both completers with priority logic
+- _ComboCompleter: Combines all completers with priority logic
 
 Public API:
 - create_repl_completer(): Factory function to create the combined completer
 - AT_TOKEN_PATTERN: Regex pattern for @token matching (used by key bindings)
+- SKILL_TOKEN_PATTERN: Regex pattern for $skill matching (used by key bindings)
 """
 
 from __future__ import annotations
@@ -34,6 +36,9 @@ from klaude_code.trace.log import DebugType, log_debug
 # single logical token.
 AT_TOKEN_PATTERN = re.compile(r'(^|\s)@(?P<frag>"[^"]*"|[^\s]*)$')
 
+# Pattern to match $skill or ¥skill token for skill completion (used by key bindings).
+SKILL_TOKEN_PATTERN = re.compile(r"^[$¥](?P<frag>\S*)$")
+
 
 def create_repl_completer() -> Completer:
     """Create and return the combined REPL completer.
@@ -121,12 +126,102 @@ class _SlashCommandCompleter(Completer):
         return bool(self._SLASH_TOKEN_RE.search(text_before))
 
 
+class _SkillCompleter(Completer):
+    """Complete skill names at the beginning of the first line.
+
+    Behavior:
+    - Only triggers when cursor is on first line and text matches $ or ¥...
+    - Shows available skills with descriptions
+    - Inserts trailing space after completion
+    """
+
+    _SKILL_TOKEN_RE = SKILL_TOKEN_PATTERN
+
+    def get_completions(
+        self,
+        document: Document,
+        complete_event,  # type: ignore[override]
+    ) -> Iterable[Completion]:
+        # Only complete on first line
+        if document.cursor_position_row != 0:
+            return
+
+        text_before = document.current_line_before_cursor
+        m = self._SKILL_TOKEN_RE.search(text_before)
+        if not m:
+            return
+
+        frag = m.group("frag").lower()
+        # Get the prefix character ($ or ¥)
+        prefix_char = text_before[0]
+        token_start = len(text_before) - len(f"{prefix_char}{m.group('frag')}")
+        start_position = token_start - len(text_before)  # negative offset
+
+        # Get available skills from SkillTool
+        skills = self._get_available_skills()
+        if not skills:
+            return
+
+        # Filter skills that match the fragment (case-insensitive)
+        matched: list[tuple[str, str, str]] = []  # (name, description, location)
+        for name, desc, location in skills:
+            if frag in name.lower() or frag in desc.lower():
+                matched.append((name, desc, location))
+
+        if not matched:
+            return
+
+        # Calculate max width for alignment
+        max_name_len = max(len(name) for name, _, _ in matched)
+        align_width = max(max_name_len, 20) + 2
+
+        for name, desc, location in matched:
+            # Format: name  [location]  description
+            # Align location tags (max length is "project" = 7, plus brackets = 9)
+            padding_name = " " * (align_width - len(name))
+            location_tag = f"[{location}]".ljust(9)
+
+            # Using HTML for formatting: bold skill name, cyan location tag, gray description
+            display_text = HTML(
+                f"<b>{name}</b>{padding_name}<style color='ansicyan'>{location_tag}</style> "
+                f"<style color='ansibrightblack'>{desc}</style>"
+            )
+            completion_text = f"${name} "
+            yield Completion(
+                text=completion_text,
+                start_position=start_position,
+                display=display_text,
+            )
+
+    def _get_available_skills(self) -> list[tuple[str, str, str]]:
+        """Get available skills from skill module.
+
+        Returns:
+            List of (name, description, location) tuples
+        """
+        try:
+            # Import here to avoid circular imports
+            from klaude_code.skill import get_available_skills
+
+            return get_available_skills()
+        except Exception:
+            return []
+
+    def is_skill_context(self, document: Document) -> bool:
+        """Check if current context is a skill completion."""
+        if document.cursor_position_row != 0:
+            return False
+        text_before = document.current_line_before_cursor
+        return bool(self._SKILL_TOKEN_RE.search(text_before))
+
+
 class _ComboCompleter(Completer):
-    """Combined completer that handles both @ file paths and / slash commands."""
+    """Combined completer that handles @ file paths, / slash commands, and $ skills."""
 
     def __init__(self) -> None:
         self._at_completer = _AtFilesCompleter()
         self._slash_completer = _SlashCommandCompleter()
+        self._skill_completer = _SkillCompleter()
 
     def get_completions(
         self,
@@ -138,6 +233,11 @@ class _ComboCompleter(Completer):
             yield from self._slash_completer.get_completions(document, complete_event)
             return
 
+        # Try skill completion (only on first line with $ prefix)
+        if document.cursor_position_row == 0 and self._skill_completer.is_skill_context(document):
+            yield from self._skill_completer.get_completions(document, complete_event)
+            return
+
         # Fall back to @ file completion
         yield from self._at_completer.get_completions(document, complete_event)
 

klaude_code/ui/modes/repl/event_handler.py

@@ -2,12 +2,14 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 
+from rich.rule import Rule
 from rich.text import Text
 
 from klaude_code import const
 from klaude_code.protocol import events
 from klaude_code.ui.core.stage_manager import Stage, StageManager
 from klaude_code.ui.modes.repl.renderer import REPLRenderer
+from klaude_code.ui.renderers.assistant import ASSISTANT_MESSAGE_MARK
 from klaude_code.ui.renderers.thinking import normalize_thinking_content
 from klaude_code.ui.rich.markdown import MarkdownStream, ThinkingMarkdown
 from klaude_code.ui.rich.theme import ThemeKey
@@ -327,7 +329,7 @@ class DisplayEventHandler:
                 theme=self.renderer.themes.thinking_markdown_theme,
                 console=self.renderer.console,
                 spinner=self.renderer.spinner_renderable(),
-                indent=2,
+                left_margin=const.MARKDOWN_LEFT_MARGIN,
                 markdown_class=ThinkingMarkdown,
             )
             self.thinking_stream.start(mdstream)
@@ -358,8 +360,8 @@ class DisplayEventHandler:
                 theme=self.renderer.themes.markdown_theme,
                 console=self.renderer.console,
                 spinner=self.renderer.spinner_renderable(),
-                mark="➤",
-                indent=2,
+                mark=ASSISTANT_MESSAGE_MARK,
+                left_margin=const.MARKDOWN_LEFT_MARGIN,
             )
             self.assistant_stream.start(mdstream)
         self.assistant_stream.append(event.content)
@@ -430,6 +432,8 @@ class DisplayEventHandler:
             emit_osc94(OSC94States.HIDDEN)
             self.spinner_status.reset()
             self.renderer.spinner_stop()
+            self.renderer.console.print(Rule(characters="-", style=ThemeKey.LINES))
+            self.renderer.print()
         await self.stage_manager.transition_to(Stage.WAITING)
         self._maybe_notify_task_finish(event)