klaude-code 1.2.6__py3-none-any.whl

klaude_code/core/tool/memory/skill_loader.py

@@ -0,0 +1,245 @@
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+from klaude_code.trace import log_debug
+
+
+@dataclass
+class Skill:
+    """Skill data structure"""
+
+    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'
+    license: str | None = None
+    allowed_tools: list[str] | None = None
+    metadata: dict[str, str] | None = None
+    skill_path: Path | None = None
+
+    def to_prompt(self) -> str:
+        """Convert skill to prompt format for agent consumption"""
+        return f"""# Skill: {self.name}
+
+{self.description}
+
+---
+
+{self.content}
+"""
+
+
+class SkillLoader:
+    """Load and manage Claude Skills from SKILL.md files"""
+
+    # User-level skills directories (checked in order, later ones override earlier ones with same name)
+    USER_SKILLS_DIRS = [
+        Path("~/.claude/skills"),
+        Path("~/.klaude/skills"),
+        Path("~/.claude/plugins/marketplaces"),
+    ]
+    # Project-level skills directory
+    PROJECT_SKILLS_DIR = Path("./.claude/skills")
+
+    def __init__(self) -> None:
+        """Initialize the skill loader"""
+        self.loaded_skills: dict[str, Skill] = {}
+
+    def load_skill(self, skill_path: Path, location: str) -> Skill | None:
+        """Load single skill from SKILL.md file
+
+        Args:
+            skill_path: Path to SKILL.md file
+            location: Skill location ('user' or 'project')
+
+        Returns:
+            Skill object or None if loading failed
+        """
+        if not skill_path.exists():
+            return None
+
+        try:
+            content = skill_path.read_text(encoding="utf-8")
+
+            # Parse YAML frontmatter
+            frontmatter: dict[str, object] = {}
+            markdown_content = content
+
+            if content.startswith("---"):
+                parts = content.split("---", 2)
+                if len(parts) >= 3:
+                    loaded: object = yaml.safe_load(parts[1])
+                    if isinstance(loaded, dict):
+                        frontmatter = dict(loaded)  # type: ignore[arg-type]
+                    markdown_content = parts[2].strip()
+
+            # Extract skill metadata
+            name = str(frontmatter.get("name", ""))
+            description = str(frontmatter.get("description", ""))
+
+            if not name or not description:
+                return None
+
+            # Process relative paths in content
+            skill_dir = skill_path.parent
+            processed_content = self._process_skill_paths(markdown_content, skill_dir)
+
+            # Create Skill object
+            license_val = frontmatter.get("license")
+            allowed_tools_val = frontmatter.get("allowed-tools")
+            metadata_val = frontmatter.get("metadata")
+
+            # Convert allowed_tools
+            allowed_tools: list[str] | None = None
+            if isinstance(allowed_tools_val, list):
+                allowed_tools = [str(t) for t in allowed_tools_val]  # type: ignore[misc]
+
+            # Convert metadata
+            metadata: dict[str, str] | None = None
+            if isinstance(metadata_val, dict):
+                metadata = {str(k): str(v) for k, v in metadata_val.items()}  # type: ignore[misc]
+
+            skill = Skill(
+                name=name,
+                description=description,
+                content=processed_content,
+                location=location,
+                license=str(license_val) if license_val is not None else None,
+                allowed_tools=allowed_tools,
+                metadata=metadata,
+                skill_path=skill_path,
+            )
+
+            return skill
+
+        except Exception:
+            return None
+
+    def discover_skills(self) -> list[Skill]:
+        """Recursively find all SKILL.md files and load them from both user and project directories
+
+        Returns:
+            List of successfully loaded Skill objects
+        """
+        skills: list[Skill] = []
+
+        # Load user-level skills from all directories
+        for user_dir in self.USER_SKILLS_DIRS:
+            expanded_dir = user_dir.expanduser()
+            if expanded_dir.exists():
+                for skill_file in expanded_dir.rglob("SKILL.md"):
+                    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 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:
+            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 user_count > 0:
+                parts.append(f"{user_count} user")
+            if project_count > 0:
+                parts.append(f"{project_count} project")
+            log_debug(f"Discovered {len(skills)} Claude Skills ({', '.join(parts)})")
+
+        return skills
+
+    def get_skill(self, name: str) -> Skill | None:
+        """Get loaded skill by name
+
+        Args:
+            name: Skill name (supports both 'skill-name' and 'namespace:skill-name')
+
+        Returns:
+            Skill object or None if not found
+        """
+        # Support both formats: 'pdf' and 'document-skills:pdf'
+        if ":" in name:
+            name = name.split(":")[-1]
+
+        return self.loaded_skills.get(name)
+
+    def list_skills(self) -> list[str]:
+        """Get list of all loaded skill names"""
+        return list(self.loaded_skills.keys())
+
+    def get_skills_xml(self) -> str:
+        """Generate Level 1 metadata in XML format for tool description
+
+        Returns:
+            XML string with all skill metadata
+        """
+        xml_parts: list[str] = []
+        for skill in self.loaded_skills.values():
+            xml_parts.append(f"""<skill>
+<name>{skill.name}</name>
+<description>{skill.description}</description>
+<location>{skill.location}</location>
+</skill>""")
+        return "\n".join(xml_parts)
+
+    def _process_skill_paths(self, content: str, skill_dir: Path) -> str:
+        """Convert relative paths to absolute paths for Level 3+
+
+        Supports:
+        - scripts/, examples/, templates/, reference/ directories
+        - Markdown document references
+        - Markdown links [text](path)
+
+        Args:
+            content: Original skill content
+            skill_dir: Directory containing the SKILL.md file
+
+        Returns:
+            Content with absolute paths
+        """
+        # Pattern 1: Directory-based paths (scripts/, examples/, etc.)
+        # e.g., "python scripts/generate.py" -> "python /abs/path/to/scripts/generate.py"
+        dir_pattern = r"\b(scripts|examples|templates|reference)/([^\s\)]+)"
+
+        def replace_dir_path(match: re.Match[str]) -> str:
+            directory = match.group(1)
+            filename = match.group(2)
+            abs_path = skill_dir / directory / filename
+            return str(abs_path)
+
+        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)"
+        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)"
+
+        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)"
+        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)"
+
+        content = re.sub(standalone_pattern, replace_standalone, content)
+
+        return content

klaude_code/core/tool/memory/skill_tool.md

@@ -0,0 +1,24 @@
+Execute a skill within the main conversation
+
+<skills_instructions>
+When users ask you to perform tasks, check if any of the available skills below can help complete the task more effectively. Skills provide specialized capabilities and domain knowledge.
+
+How to use skills:
+- Invoke skills using this tool with the skill name only (no arguments)
+- When you invoke a skill, you will see <command-message>The "{name}" skill is loading</command-message>
+- The skill's prompt will expand and provide detailed instructions on how to complete the task
+
+Examples:
+- command: "pdf" - invoke the pdf skill
+- command: "xlsx" - invoke the xlsx skill
+- command: "document-skills:pdf" - invoke using fully qualified name
+
+Important:
+- Only use skills listed in <available_skills> below
+- Do not invoke a skill that is already running
+- Do not use this tool for built-in CLI commands (like /help, /clear, etc.)
+</skills_instructions>
+
+<available_skills>
+$skills_xml
+</available_skills>

klaude_code/core/tool/memory/skill_tool.py

@@ -0,0 +1,97 @@
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from klaude_code.core.tool.memory.skill_loader import SkillLoader
+from klaude_code.core.tool.tool_abc import ToolABC, load_desc
+from klaude_code.core.tool.tool_registry import register
+from klaude_code.protocol import llm_param, model, tools
+
+
+@register(tools.SKILL)
+class SkillTool(ToolABC):
+    """Tool to execute/load a skill within the main conversation"""
+
+    _skill_loader: SkillLoader | None = None
+
+    @classmethod
+    def set_skill_loader(cls, loader: SkillLoader) -> None:
+        """Set the skill loader instance"""
+        cls._skill_loader = loader
+
+    @classmethod
+    def schema(cls) -> llm_param.ToolSchema:
+        """Generate schema with embedded available skills metadata"""
+        skills_xml = cls._generate_skills_xml()
+
+        return llm_param.ToolSchema(
+            name=tools.SKILL,
+            type="function",
+            description=load_desc(Path(__file__).parent / "skill_tool.md", {"skills_xml": skills_xml}),
+            parameters={
+                "type": "object",
+                "properties": {
+                    "command": {
+                        "type": "string",
+                        "description": "Name of the skill to execute",
+                    }
+                },
+                "required": ["command"],
+            },
+        )
+
+    @classmethod
+    def _generate_skills_xml(cls) -> str:
+        """Generate XML format skills metadata"""
+        if not cls._skill_loader:
+            return ""
+
+        xml_parts: list[str] = []
+        for skill in cls._skill_loader.loaded_skills.values():
+            xml_parts.append(f"""<skill>
+<name>{skill.name}</name>
+<description>{skill.description}</description>
+<location>{skill.location}</location>
+</skill>""")
+        return "\n".join(xml_parts)
+
+    class SkillArguments(BaseModel):
+        command: str
+
+    @classmethod
+    async def call(cls, arguments: str) -> model.ToolResultItem:
+        """Load and return full skill content"""
+        try:
+            args = cls.SkillArguments.model_validate_json(arguments)
+        except ValueError as e:
+            return model.ToolResultItem(
+                status="error",
+                output=f"Invalid arguments: {e}",
+            )
+
+        if not cls._skill_loader:
+            return model.ToolResultItem(
+                status="error",
+                output="Skill loader not initialized",
+            )
+
+        skill = cls._skill_loader.get_skill(args.command)
+
+        if not skill:
+            available = ", ".join(cls._skill_loader.list_skills())
+            return model.ToolResultItem(
+                status="error",
+                output=f"Skill '{args.command}' does not exist. Available skills: {available}",
+            )
+
+        # Get base directory from skill_path
+        base_dir = str(skill.skill_path.parent) if skill.skill_path else "unknown"
+
+        # Return with loading message format
+        result = f"""<command-message>The "{skill.name}" skill is running</command-message>
+<command-name>{skill.name}</command-name>
+
+Base directory for this skill: {base_dir}
+
+{skill.to_prompt()}"""
+        return model.ToolResultItem(status="success", output=result)

klaude_code/core/tool/shell/bash_tool.md

@@ -0,0 +1,43 @@
+Runs a shell command and returns its output.
+
+### Usage Notes
+- When searching for text or files, prefer using `rg`, `rg --files` or `fd` respectively because `rg` and `fd` is much faster than alternatives like `grep` and `find`. (If these command is not found, then use alternatives.)
+
+### Committing changes with git
+Only create commits when requested by the user. If unclear, ask first. When the user asks you to create a new git commit, follow these steps carefully:
+
+Git Safety Protocol:
+- NEVER update the git config
+- NEVER run destructive/irreversible git commands (like push --force, hard reset, etc) unless the user explicitly requests them 
+- NEVER skip hooks (--no-verify, --no-gpg-sign, etc) unless the user explicitly requests it
+- NEVER run force push to main/master, warn the user if they request it
+- Avoid git commit --amend.  ONLY use --amend when either (1) user explicitly requested amend OR (2) adding edits from pre-commit hook (additional instructions below) 
+- Before amending: ALWAYS check authorship (git log -1 --format='%an %ae')
+- NEVER commit changes unless the user explicitly asks you to. It is VERY IMPORTANT to only commit when explicitly asked, otherwise the user will feel that you are being too proactive.
+
+1. You have the capability to call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, batch your tool calls together for optimal performance. run the following bash commands in parallel, each using the Bash tool:
+  - Run a git status command to see all untracked files.
+  - Run a git diff command to see both staged and unstaged changes that will be committed.
+  - Run a git log command to see recent commit messages, so that you can follow this repository's commit message style.
+2. Analyze all staged changes (both previously staged and newly added) and draft a commit message:
+  - Summarize the nature of the changes (eg. new feature, enhancement to an existing feature, bug fix, refactoring, test, docs, etc.). Ensure the message accurately reflects the changes and their purpose (i.e. "add" means a wholly new feature, "update" means an enhancement to an existing feature, "fix" means a bug fix, etc.).
+  - Do not commit files that likely contain secrets (.env, credentials.json, etc). Warn the user if they specifically request to commit those files
+  - Draft a concise (1-2 sentences) commit message that focuses on the "why" rather than the "what"
+  - Ensure it accurately reflects the changes and their purpose
+3. You have the capability to call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, batch your tool calls together for optimal performance. run the following commands in parallel:
+   - Add relevant untracked files to the staging area.
+   - Run git status to make sure the commit succeeded.
+4. If the commit fails due to pre-commit hook changes, retry the commit ONCE to include these automated changes. If it fails again, it usually means a pre-commit hook is preventing the commit. If the commit succeeds but you notice that files were modified by the pre-commit hook, you MUST amend your commit to include them.
+
+Important notes:
+- NEVER run additional commands to read or explore code, besides git bash commands
+- NEVER use the TodoWrite or Task tools
+- DO NOT push to the remote repository unless the user explicitly asks you to do so
+- IMPORTANT: Never use git commands with the -i flag (like git rebase -i or git add -i) since they require interactive input which is not supported.
+- If there are no changes to commit (i.e., no untracked files and no modifications), do not create an empty commit
+- In order to ensure good formatting, ALWAYS pass the commit message via a HEREDOC, a la this example:<example>
+git commit -m "$(cat <<'EOF'
+   Commit message here.
+   EOF
+   )"
+</example>

klaude_code/core/tool/shell/bash_tool.py

@@ -0,0 +1,123 @@
+import asyncio
+import re
+import subprocess
+from pathlib import Path
+
+from pydantic import BaseModel
+
+from klaude_code import const
+from klaude_code.core.tool.shell.command_safety import is_safe_command
+from klaude_code.core.tool.tool_abc import ToolABC, load_desc
+from klaude_code.core.tool.tool_registry import register
+from klaude_code.protocol import llm_param, model, tools
+
+# Regex to strip ANSI escape sequences from command output
+_ANSI_ESCAPE_RE = re.compile(r"\x1b\[[0-9;]*m")
+
+
+@register(tools.BASH)
+class BashTool(ToolABC):
+    @classmethod
+    def schema(cls) -> llm_param.ToolSchema:
+        return llm_param.ToolSchema(
+            name=tools.BASH,
+            type="function",
+            description=load_desc(Path(__file__).parent / "bash_tool.md"),
+            parameters={
+                "type": "object",
+                "properties": {
+                    "command": {
+                        "type": "string",
+                        "description": "The bash command to run",
+                    },
+                    "timeout_ms": {
+                        "type": "integer",
+                        "description": f"The timeout for the command in milliseconds, default is {const.BASH_DEFAULT_TIMEOUT_MS}",
+                        "default": const.BASH_DEFAULT_TIMEOUT_MS,
+                    },
+                },
+                "required": ["command"],
+            },
+        )
+
+    class BashArguments(BaseModel):
+        command: str
+        timeout_ms: int = const.BASH_DEFAULT_TIMEOUT_MS
+
+    @classmethod
+    async def call(cls, arguments: str) -> model.ToolResultItem:
+        try:
+            args = BashTool.BashArguments.model_validate_json(arguments)
+        except ValueError as e:
+            return model.ToolResultItem(
+                status="error",
+                output=f"Invalid arguments: {e}",
+            )
+        return await cls.call_with_args(args)
+
+    @classmethod
+    async def call_with_args(cls, args: BashArguments) -> model.ToolResultItem:
+        # Safety check: only execute commands proven as "known safe"
+        result = is_safe_command(args.command)
+        if not result.is_safe:
+            return model.ToolResultItem(
+                status="error",
+                output=f"Command rejected: {result.error_msg}",
+            )
+
+        # Run the command using bash -lc so shell semantics work (pipes, &&, etc.)
+        # Capture stdout/stderr, respect timeout, and return a ToolMessage.
+        cmd = ["bash", "-lc", args.command]
+        timeout_sec = max(0.0, args.timeout_ms / 1000.0)
+
+        try:
+            completed = await asyncio.to_thread(
+                subprocess.run,
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=timeout_sec,
+                check=False,
+            )
+
+            stdout = _ANSI_ESCAPE_RE.sub("", completed.stdout or "")
+            stderr = _ANSI_ESCAPE_RE.sub("", completed.stderr or "")
+            rc = completed.returncode
+
+            if rc == 0:
+                output = stdout if stdout else ""
+                # Include stderr if there is useful diagnostics despite success
+                if stderr.strip():
+                    output = (output + ("\n" if output else "")) + f"[stderr]\n{stderr}"
+                return model.ToolResultItem(
+                    status="success",
+                    output=output.strip(),
+                )
+            else:
+                combined = ""
+                if stdout.strip():
+                    combined += f"[stdout]\n{stdout}\n"
+                if stderr.strip():
+                    combined += f"[stderr]\n{stderr}"
+                if not combined:
+                    combined = f"Command exited with code {rc}"
+                return model.ToolResultItem(
+                    status="error",
+                    output=combined.strip(),
+                )
+
+        except subprocess.TimeoutExpired:
+            return model.ToolResultItem(
+                status="error",
+                output=f"Timeout after {args.timeout_ms} ms running: {args.command}",
+            )
+        except FileNotFoundError:
+            return model.ToolResultItem(
+                status="error",
+                output="bash not found on system path",
+            )
+        except Exception as e:  # safeguard against unexpected failures
+            return model.ToolResultItem(
+                status="error",
+                output=f"Execution error: {e}",
+            )