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

klaude_code/skill/assets/skill-creator/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: skill-creator
+description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
+metadata:
+  short-description: Create or update a skill
+---
+
+# Skill Creator
+
+This skill provides guidance for creating effective skills.
+
+## About Skills
+
+Skills are modular, self-contained packages that extend the agent's capabilities by providing
+specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific
+domains or tasks - they transform the agent from a general-purpose assistant into a specialized
+agent equipped with procedural knowledge.
+
+### What Skills Provide
+
+1. Specialized workflows - Multi-step procedures for specific domains
+2. Tool integrations - Instructions for working with specific file formats or APIs
+3. Domain expertise - Company-specific knowledge, schemas, business logic
+4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks
+
+## Core Principles
+
+### Concise is Key
+
+The context window is a public good. Skills share the context window with everything else:
+system prompt, conversation history, other Skills' metadata, and the actual user request.
+
+**Default assumption: The agent is already very smart.** Only add context the agent doesn't
+already have. Challenge each piece of information: "Does the agent really need this explanation?"
+and "Does this paragraph justify its token cost?"
+
+Prefer concise examples over verbose explanations.
+
+### Anatomy of a Skill
+
+Every skill consists of a required SKILL.md file and optional bundled resources:
+
+```
+skill-name/
+├── SKILL.md (required)
+│   ├── YAML frontmatter metadata (required)
+│   │   ├── name: (required)
+│   │   └── description: (required)
+│   └── Markdown instructions (required)
+└── Bundled Resources (optional)
+    ├── scripts/          - Executable code (Python/Bash/etc.)
+    ├── references/       - Documentation intended to be loaded into context as needed
+    └── assets/           - Files used in output (templates, icons, fonts, etc.)
+```
+
+#### SKILL.md (required)
+
+Every SKILL.md consists of:
+
+- **Frontmatter** (YAML): Contains `name` and `description` fields. These are the only fields
+  that determine when the skill gets used, thus it is very important to be clear and comprehensive
+  in describing what the skill is, and when it should be used.
+- **Body** (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the
+  skill triggers (if at all).
+
+#### Bundled Resources (optional)
+
+##### Scripts (`scripts/`)
+
+Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are
+repeatedly rewritten.
+
+- **When to include**: When the same code is being rewritten repeatedly or deterministic
+  reliability is needed
+- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks
+- **Benefits**: Token efficient, deterministic, may be executed without loading into context
+
+##### References (`references/`)
+
+Documentation and reference material intended to be loaded as needed into context.
+
+- **When to include**: For documentation that the agent should reference while working
+- **Examples**: `references/schema.md` for database schemas, `references/api_docs.md` for
+  API specifications
+- **Benefits**: Keeps SKILL.md lean, loaded only when needed
+
+##### Assets (`assets/`)
+
+Files not intended to be loaded into context, but rather used within the output.
+
+- **When to include**: When the skill needs files that will be used in the final output
+- **Examples**: `assets/logo.png` for brand assets, `assets/template.html` for HTML templates
+- **Benefits**: Separates output resources from documentation
+
+## Skill Creation Process
+
+Skill creation involves these steps:
+
+1. Understand the skill with concrete examples
+2. Plan reusable skill contents (scripts, references, assets)
+3. Create the skill directory structure
+4. Write SKILL.md with proper frontmatter
+5. Add bundled resources as needed
+6. Test and iterate based on real usage
+
+### Skill Naming
+
+- Use lowercase letters, digits, and hyphens only
+- Prefer short, verb-led phrases that describe the action
+- Name the skill folder exactly after the skill name
+
+### Writing Guidelines
+
+Always use imperative/infinitive form.
+
+#### Frontmatter
+
+Write the YAML frontmatter with `name` and `description`:
+
+- `name`: The skill name (required)
+- `description`: This is the primary triggering mechanism for your skill. Include both what
+  the Skill does and specific triggers/contexts for when to use it. Include all "when to use"
+  information here - Not in the body.
+
+#### Body
+
+Write instructions for using the skill and its bundled resources. Keep SKILL.md body to the
+essentials and under 500 lines to minimize context bloat.
+
+## Skill Storage Locations
+
+Skills can be stored in multiple locations with the following priority (higher priority overrides lower):
+
+| Priority | Scope   | Path                        | Description           |
+|----------|---------|-----------------------------|-----------------------|
+| 1        | Project | `.claude/skills/`           | Current project only  |
+| 2        | User    | `~/.klaude/skills/`         | User-level            |
+| 3        | User    | `~/.claude/skills/`         | User-level (Claude)   |
+| 4        | System  | `~/.klaude/skills/.system/` | Built-in system skills|

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