emdash-core 0.1.7__py3-none-any.whl → 0.1.25__py3-none-any.whl

emdash_core/agent/skills.py

@@ -0,0 +1,319 @@
+"""Skill loader from .emdash/skills/*/SKILL.md files.
+
+Skills are markdown-based instruction files that teach the agent how to
+perform specific, repeatable tasks. They can be automatically applied
+when relevant or explicitly invoked via /skill_name.
+
+Similar to Claude Code's skills system:
+https://docs.anthropic.com/en/docs/claude-code/skills
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+from ..utils.logger import log
+
+
+@dataclass
+class Skill:
+    """A skill configuration loaded from SKILL.md.
+
+    Attributes:
+        name: Unique skill identifier (from directory name or frontmatter)
+        description: Brief description of when to use this skill
+        instructions: The main prompt/instructions content
+        tools: List of tools this skill needs access to
+        user_invocable: Whether skill can be invoked with /name
+        file_path: Source file path
+    """
+
+    name: str
+    description: str = ""
+    instructions: str = ""
+    tools: list[str] = field(default_factory=list)
+    user_invocable: bool = False
+    file_path: Optional[Path] = None
+
+
+class SkillRegistry:
+    """Registry for managing loaded skills.
+
+    Singleton that maintains the list of available skills
+    and provides lookup functionality.
+    """
+
+    _instance: Optional["SkillRegistry"] = None
+    _skills: dict[str, Skill]
+    _skills_dir: Optional[Path]
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._skills = {}
+            cls._instance._skills_dir = None
+        return cls._instance
+
+    @classmethod
+    def get_instance(cls) -> "SkillRegistry":
+        """Get the singleton instance."""
+        return cls()
+
+    @classmethod
+    def reset(cls) -> None:
+        """Reset the singleton instance."""
+        if cls._instance is not None:
+            cls._instance._skills = {}
+            cls._instance._skills_dir = None
+
+    def load_skills(self, skills_dir: Optional[Path] = None) -> dict[str, Skill]:
+        """Load skills from .emdash/skills/ directory.
+
+        Each skill is a directory containing a SKILL.md file:
+
+        ```
+        .emdash/skills/
+        ├── commit/
+        │   └── SKILL.md
+        └── review-pr/
+            └── SKILL.md
+        ```
+
+        SKILL.md format:
+        ```markdown
+        ---
+        name: commit
+        description: Generate commit messages following conventions
+        user_invocable: true
+        tools: [execute_command, read_file]
+        ---
+
+        # Commit Message Generation
+
+        Instructions for the skill...
+        ```
+
+        Args:
+            skills_dir: Directory containing skill subdirectories.
+                       Defaults to .emdash/skills/ in cwd.
+
+        Returns:
+            Dict mapping skill name to Skill
+        """
+        if skills_dir is None:
+            skills_dir = Path.cwd() / ".emdash" / "skills"
+
+        self._skills_dir = skills_dir
+
+        if not skills_dir.exists():
+            return {}
+
+        skills = {}
+
+        # Look for SKILL.md in subdirectories
+        for skill_dir in skills_dir.iterdir():
+            if not skill_dir.is_dir():
+                continue
+
+            skill_file = skill_dir / "SKILL.md"
+            if not skill_file.exists():
+                # Also try lowercase
+                skill_file = skill_dir / "skill.md"
+                if not skill_file.exists():
+                    continue
+
+            try:
+                skill = _parse_skill_file(skill_file, skill_dir.name)
+                if skill:
+                    skills[skill.name] = skill
+                    self._skills[skill.name] = skill
+                    log.debug(f"Loaded skill: {skill.name}")
+            except Exception as e:
+                log.warning(f"Failed to load skill from {skill_file}: {e}")
+
+        if skills:
+            log.info(f"Loaded {len(skills)} skills")
+
+        return skills
+
+    def get_skill(self, name: str) -> Optional[Skill]:
+        """Get a specific skill by name.
+
+        Args:
+            name: Skill name
+
+        Returns:
+            Skill or None if not found
+        """
+        return self._skills.get(name)
+
+    def list_skills(self) -> list[str]:
+        """List available skill names.
+
+        Returns:
+            List of skill names
+        """
+        return list(self._skills.keys())
+
+    def get_all_skills(self) -> dict[str, Skill]:
+        """Get all loaded skills.
+
+        Returns:
+            Dict mapping skill name to Skill
+        """
+        return self._skills.copy()
+
+    def get_user_invocable_skills(self) -> list[Skill]:
+        """Get skills that can be invoked with /name.
+
+        Returns:
+            List of user-invocable skills
+        """
+        return [s for s in self._skills.values() if s.user_invocable]
+
+    def get_skills_for_prompt(self) -> str:
+        """Generate skills section for system prompt.
+
+        Returns:
+            Formatted string describing available skills
+        """
+        if not self._skills:
+            return ""
+
+        lines = ["## Available Skills\n"]
+        lines.append("The following skills are available. Use them when the task matches their description:\n")
+
+        for skill in self._skills.values():
+            invocable = " (user-invocable: /{})".format(skill.name) if skill.user_invocable else ""
+            lines.append(f"- **{skill.name}**: {skill.description}{invocable}")
+
+        lines.append("")
+        lines.append("To activate a skill, use the `skill` tool with the skill name.")
+        lines.append("")
+
+        return "\n".join(lines)
+
+
+def _parse_skill_file(file_path: Path, default_name: str) -> Optional[Skill]:
+    """Parse a single SKILL.md file.
+
+    Args:
+        file_path: Path to the SKILL.md file
+        default_name: Default name from directory (used if not in frontmatter)
+
+    Returns:
+        Skill or None if parsing fails
+    """
+    content = file_path.read_text()
+
+    # Extract frontmatter
+    frontmatter = {}
+    body = content
+
+    if content.startswith("---"):
+        parts = content.split("---", 2)
+        if len(parts) >= 3:
+            frontmatter = _parse_frontmatter(parts[1])
+            body = parts[2].strip()
+
+    # Get name from frontmatter or use directory name
+    name = frontmatter.get("name", default_name)
+
+    # Validate name format (lowercase, hyphens, max 64 chars)
+    if len(name) > 64:
+        log.warning(f"Skill name '{name}' exceeds 64 characters, truncating")
+        name = name[:64]
+
+    return Skill(
+        name=name,
+        description=frontmatter.get("description", ""),
+        instructions=body,
+        tools=frontmatter.get("tools", []),
+        user_invocable=frontmatter.get("user_invocable", False),
+        file_path=file_path,
+    )
+
+
+def _parse_frontmatter(frontmatter_str: str) -> dict:
+    """Parse YAML-like frontmatter.
+
+    Simple parser for key: value pairs.
+
+    Args:
+        frontmatter_str: Frontmatter string
+
+    Returns:
+        Dict of parsed values
+    """
+    result = {}
+
+    for line in frontmatter_str.strip().split("\n"):
+        if ":" not in line:
+            continue
+
+        key, value = line.split(":", 1)
+        key = key.strip()
+        value = value.strip()
+
+        # Parse boolean values
+        if value.lower() == "true":
+            result[key] = True
+        elif value.lower() == "false":
+            result[key] = False
+        # Parse list values
+        elif value.startswith("[") and value.endswith("]"):
+            items = value[1:-1].split(",")
+            result[key] = [item.strip().strip("'\"") for item in items if item.strip()]
+        else:
+            result[key] = value.strip("'\"")
+
+    return result
+
+
+# Convenience functions
+
+
+def load_skills(skills_dir: Optional[Path] = None) -> dict[str, Skill]:
+    """Load skills from directory.
+
+    Args:
+        skills_dir: Optional skills directory
+
+    Returns:
+        Dict mapping skill name to Skill
+    """
+    registry = SkillRegistry.get_instance()
+    return registry.load_skills(skills_dir)
+
+
+def get_skill(name: str) -> Optional[Skill]:
+    """Get a specific skill by name.
+
+    Args:
+        name: Skill name
+
+    Returns:
+        Skill or None if not found
+    """
+    registry = SkillRegistry.get_instance()
+    return registry.get_skill(name)
+
+
+def list_skills() -> list[str]:
+    """List available skill names.
+
+    Returns:
+        List of skill names
+    """
+    registry = SkillRegistry.get_instance()
+    return registry.list_skills()
+
+
+def get_user_invocable_skills() -> list[Skill]:
+    """Get skills that can be invoked with /name.
+
+    Returns:
+        List of user-invocable skills
+    """
+    registry = SkillRegistry.get_instance()
+    return registry.get_user_invocable_skills()

emdash_core/agent/toolkit.py

@@ -103,6 +103,9 @@ class AgentToolkit:
         self.register_tool(GlobTool(self.connection))
         self.register_tool(WebTool(self.connection))
 
+        # Register skill tools and load skills
+        self._register_skill_tools()
+
         # Register read-only file tools (always available)
         self.register_tool(ReadFileTool(self._repo_root, self.connection))
         self.register_tool(ListFilesTool(self._repo_root, self.connection))
@@ -123,6 +126,9 @@ class AgentToolkit:
         # Register sub-agent tools for spawning lightweight agents
         self._register_subagent_tools()
 
+        # Register mode tools
+        self._register_mode_tools()
+
         # Register task management tools (not in plan mode)
         if not self.plan_mode:
             self._register_task_tools()
@@ -153,6 +159,25 @@ class AgentToolkit:
         self.register_tool(TaskTool(repo_root=self._repo_root, connection=self.connection))
         self.register_tool(TaskOutputTool(repo_root=self._repo_root, connection=self.connection))
 
+    def _register_mode_tools(self) -> None:
+        """Register mode switching tools.
+
+        - enter_mode: Available in code mode to enter other modes (e.g., plan)
+        - exit_plan: Available in plan mode to submit plan and request approval
+        - get_mode: Always available to check current mode
+        """
+        from .tools.modes import EnterModeTool, ExitPlanModeTool, GetModeTool
+
+        # get_mode is always available
+        self.register_tool(GetModeTool())
+
+        if self.plan_mode:
+            # In plan mode: can exit with plan submission
+            self.register_tool(ExitPlanModeTool())
+        else:
+            # In code mode: can enter other modes
+            self.register_tool(EnterModeTool())
+
     def _register_task_tools(self) -> None:
         """Register task management tools.
 
@@ -187,6 +212,29 @@ class AgentToolkit:
         self.register_tool(GetSpecTool())
         self.register_tool(UpdateSpecTool())
 
+    def _register_skill_tools(self) -> None:
+        """Register skill tools and load skills from .emdash/skills/.
+
+        Skills are markdown-based instruction files that teach the agent
+        how to perform specific, repeatable tasks. Similar to Claude Code's
+        skills system.
+        """
+        from .tools.skill import SkillTool, ListSkillsTool
+        from .skills import SkillRegistry
+
+        # Load skills from .emdash/skills/
+        skills_dir = self._repo_root / ".emdash" / "skills"
+        registry = SkillRegistry.get_instance()
+        registry.load_skills(skills_dir)
+
+        # Register skill tools
+        self.register_tool(SkillTool(self.connection))
+        self.register_tool(ListSkillsTool(self.connection))
+
+        skills_count = len(registry.list_skills())
+        if skills_count > 0:
+            log.info(f"Registered skill tools with {skills_count} skills available")
+
     def _register_mcp_tools(self) -> None:
         """Register GitHub MCP tools if available.
 

emdash_core/agent/tools/__init__.py

@@ -43,7 +43,7 @@ from .tasks import (
 from .plan import PlanExplorationTool
 
 # Mode tools
-from .modes import AgentMode, ModeState, SwitchModeTool, GetModeTool
+from .modes import AgentMode, ModeState, EnterModeTool, ExitPlanModeTool, GetModeTool
 
 # Spec tools
 from .spec import SubmitSpecTool, GetSpecTool, UpdateSpecTool
@@ -111,7 +111,8 @@ __all__ = [
     # Mode
     "AgentMode",
     "ModeState",
-    "SwitchModeTool",
+    "EnterModeTool",
+    "ExitPlanModeTool",
     "GetModeTool",
     # Spec
     "SubmitSpecTool",