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

klaude_code/skill/assets/dev-docs/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: dev-docs
+description: Manage development documentation for complex tasks. Use this skill when users want to create a strategic plan with structured task breakdown, or update development documentation before context compaction/reset. Triggers include "create a plan", "dev docs", "update docs before context reset", "context limit approaching".
+metadata:
+  short-description: Create and update development documentation
+---
+
+# Dev Docs
+
+Manage development documentation for complex, multi-phase tasks. This skill supports two workflows:
+1. **Create**: Generate a comprehensive strategic plan with structured task breakdown
+2. **Update**: Update documentation before context compaction or reset
+
+## Create Development Plan
+
+When creating a new plan:
+
+1. **Analyze the request** and determine the scope of planning needed
+2. **Examine relevant files** in the codebase to understand current state
+3. **Create a structured plan** with:
+   - Executive Summary
+   - Current State Analysis
+   - Proposed Future State
+   - Implementation Phases (broken into sections)
+   - Detailed Tasks (actionable items with clear acceptance criteria)
+   - Risk Assessment and Mitigation Strategies
+   - Success Metrics
+   - Required Resources and Dependencies
+
+4. **Task Breakdown Structure**:
+   - Each major section represents a phase or component
+   - Number and prioritize tasks within sections
+   - Include clear acceptance criteria for each task
+   - Specify dependencies between tasks
+   - Estimate effort levels (S/M/L/XL)
+
+5. **Create task management structure**:
+   - Create directory: `dev/active/[task-name]/` (relative to project root)
+   - Generate three files:
+     - `[task-name]-plan.md` - The comprehensive plan
+     - `[task-name]-context.md` - Key files, decisions, dependencies
+     - `[task-name]-tasks.md` - Checklist format for tracking progress
+   - Include "Last Updated: YYYY-MM-DD" in each file
+
+6. **Stop and Consult**: Pause and negotiate the plan with the user.
+
+### Quality Standards
+
+- Plans must be self-contained with all necessary context
+- Use clear, actionable language
+- Include specific technical details where relevant
+- Consider both technical and business perspectives
+- Account for potential risks and edge cases
+
+## Update Development Documentation
+
+When approaching context limits or before context reset:
+
+### 1. Update Active Task Documentation
+
+For each task in `/dev/active/`:
+
+Update `[task-name]-context.md` with:
+- Current implementation state
+- Key decisions made this session
+- Files modified and why
+- Any blockers or issues discovered
+- Next immediate steps
+- Last Updated timestamp
+
+Update `[task-name]-tasks.md` with:
+- Mark completed tasks with checkmark
+- Add any new tasks discovered
+- Update in-progress tasks with current status
+- Reorder priorities if needed
+
+### 2. Capture Session Context
+
+Include any relevant information about:
+- Complex problems solved
+- Architectural decisions made
+- Tricky bugs found and fixed
+- Integration points discovered
+- Testing approaches used
+- Performance optimizations made
+
+### 3. Update Memory (if applicable)
+
+- Store any new patterns or solutions in project memory/documentation
+- Update entity relationships discovered
+- Add observations about system behavior
+
+### 4. Document Unfinished Work
+
+- What was being worked on when context limit approached
+- Exact state of any partially completed features
+- Commands that need to be run on restart
+- Any temporary workarounds that need permanent fixes
+
+### 5. Create Handoff Notes
+
+If switching to a new conversation:
+- Exact file and line being edited
+- The goal of current changes
+- Any uncommitted changes that need attention
+- Test commands to verify work
+
+**Priority**: Focus on capturing information that would be hard to rediscover or reconstruct from code alone.

klaude_code/skill/assets/handoff/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: handoff
+description: Write a HANDOFF.md file for another agent to continue the conversation. Use this skill when switching to a new conversation/session and need to pass context to the next agent. Triggers include "handoff", "write handoff", "create handoff", "pass to another agent".
+metadata:
+  short-description: Write handoff document for agent continuation
+---
+
+# Handoff
+
+Write a HANDOFF.md file in the current working directory for another agent to continue this conversation.
+
+Extract relevant context from the conversation to facilitate continuing this work. Write from the user's perspective (first person: "I did...", "I told you...").
+
+## Consider What Would Be Useful
+
+- What did the user just do or implement?
+- What instructions did the user give that are still relevant (e.g., follow patterns in the codebase)?
+- Did the user provide a plan or spec that should be included?
+- What important information did the user share (certain libraries, patterns, constraints, preferences)?
+- What key technical details were discovered (APIs, methods, patterns)?
+- What caveats, limitations, or open questions remain?
+
+Extract only what matters for the specific goal. Skip irrelevant questions. Choose an appropriate length based on the complexity.
+
+Focus on capabilities and behavior, not file-by-file changes. Avoid excessive implementation details (variable names, storage keys, constants) unless critical.
+
+## Format
+
+- Plain text with bullets
+- No markdown headers, no bold/italic, no code fences
+- Use workspace-relative paths for files
+- List relevant file or directory paths at the end:
+
+```
+@src/project/main.py
+@src/project/llm/
+```
+
+If the user's goal is unclear, ask for clarification.

klaude_code/skill/assets/jj-workspace/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: jj-workspace
+description: Create a jj workspace before starting work to enable parallel Claude sessions. Use this skill when starting a new task that should be isolated from other concurrent work. Triggers include "jj workspace", "parallel work", "create workspace", "isolated workspace".
+metadata:
+  short-description: Create jj workspace for parallel work
+---
+
+# JJ Workspace
+
+Create a dedicated jj workspace before starting any task. This allows multiple Claude sessions to work in parallel without conflicts.
+
+## Steps
+
+1. Generate a short, descriptive workspace name based on the task (e.g., `workspace-add-login` or `workspace-fix-typo`)
+2. Run `jj workspace add <workspace-name>` to create the workspace
+3. Change into the workspace directory: `cd <workspace-name>`
+4. Describe the change: `jj describe -m '<brief task description>'`
+5. Continue all subsequent work within this workspace directory
+
+If no task is provided, ask the user for a task description.

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()