""" Skill Loader - Load Claude Skills Supports loading skills from SKILL.md files and providing them to Agent """ import re from dataclasses import dataclass from pathlib import Path from typing import Dict, List, Optional import yaml @dataclass class Skill: """Skill data structure""" name: str description: str content: str license: Optional[str] = None allowed_tools: Optional[List[str]] = None metadata: Optional[Dict[str, str]] = None skill_path: Optional[Path] = None def to_prompt(self) -> str: """Convert skill to prompt format""" # Inject skill root directory path for context skill_root = str(self.skill_path.parent) if self.skill_path else "unknown" return f""" # Skill: {self.name} {self.description} **Skill Root Directory:** `{skill_root}` All files and references in this skill are relative to this directory. --- {self.content} """ class SkillLoader: """Skill loader""" def __init__(self, skills_dir: str = "./skills"): """ Initialize Skill Loader Args: skills_dir: Skills directory path """ self.skills_dir = Path(skills_dir) self.loaded_skills: Dict[str, Skill] = {} def load_skill(self, skill_path: Path) -> Optional[Skill]: """ Load single skill from SKILL.md file Args: skill_path: SKILL.md file path Returns: Skill object, or None if loading fails """ try: content = skill_path.read_text(encoding="utf-8") # Parse YAML frontmatter frontmatter_match = re.match(r"^---\n(.*?)\n---\n(.*)$", content, re.DOTALL) if not frontmatter_match: print(f"⚠️ {skill_path} missing YAML frontmatter") return None frontmatter_text = frontmatter_match.group(1) skill_content = frontmatter_match.group(2).strip() # Parse YAML try: frontmatter = yaml.safe_load(frontmatter_text) except yaml.YAMLError as e: print(f"❌ Failed to parse YAML frontmatter: {e}") return None # Required fields if "name" not in frontmatter or "description" not in frontmatter: print(f"⚠️ {skill_path} missing required fields (name or description)") return None # Get skill directory (parent of SKILL.md) skill_dir = skill_path.parent # Replace relative paths in content with absolute paths # This ensures scripts and resources can be found from any working directory processed_content = self._process_skill_paths(skill_content, skill_dir) # Create Skill object skill = Skill( name=frontmatter["name"], description=frontmatter["description"], content=processed_content, license=frontmatter.get("license"), allowed_tools=frontmatter.get("allowed-tools"), metadata=frontmatter.get("metadata"), skill_path=skill_path, ) return skill except Exception as e: print(f"❌ Failed to load skill ({skill_path}): {e}") return None def _process_skill_paths(self, content: str, skill_dir: Path) -> str: """ Process skill content to replace relative paths with absolute paths. Supports Progressive Disclosure Level 3+: converts relative file references to absolute paths so Agent can easily read nested resources. Args: content: Original skill content skill_dir: Skill directory path Returns: Processed content with absolute paths """ import re # Pattern 1: Directory-based paths (scripts/, references/, assets/) # See https://agentskills.io/specification#optional-directories def replace_dir_path(match): prefix = match.group(1) # e.g., "python " or "`" rel_path = match.group(2) # e.g., "scripts/with_server.py" abs_path = skill_dir / rel_path if abs_path.exists(): return f"{prefix}{abs_path}" return match.group(0) pattern_dirs = r"(python\s+|`)((?:scripts|references|assets)/[^\s`\)]+)" content = re.sub(pattern_dirs, replace_dir_path, content) # Pattern 2: Direct markdown/document references (forms.md, reference.md, etc.) # Matches phrases like "see reference.md" or "read forms.md" def replace_doc_path(match): prefix = match.group(1) # e.g., "see ", "read " filename = match.group(2) # e.g., "reference.md" suffix = match.group(3) # e.g., punctuation abs_path = skill_dir / filename if abs_path.exists(): # Add helpful instruction for Agent return f"{prefix}`{abs_path}` (use read_file to access){suffix}" return match.group(0) # Match patterns like: "see reference.md" or "read forms.md" pattern_docs = r"(see|read|refer to|check)\s+([a-zA-Z0-9_-]+\.(?:md|txt|json|yaml))([.,;\s])" content = re.sub(pattern_docs, replace_doc_path, content, flags=re.IGNORECASE) # Pattern 3: Markdown links - supports multiple formats: # - [`filename.md`](filename.md) - simple filename # - [text](./reference/file.md) - relative path with ./ # - [text](scripts/file.js) - directory-based path # Matches patterns like: "Read [`docx-js.md`](docx-js.md)" or "Load [Guide](./reference/guide.md)" def replace_markdown_link(match): prefix = match.group(1) if match.group(1) else "" # e.g., "Read ", "Load ", or empty link_text = match.group(2) # e.g., "`docx-js.md`" or "Guide" filepath = match.group(3) # e.g., "docx-js.md", "./reference/file.md", "scripts/file.js" # Remove leading ./ if present clean_path = filepath[2:] if filepath.startswith("./") else filepath abs_path = skill_dir / clean_path if abs_path.exists(): # Preserve the link text style (with or without backticks) return f"{prefix}[{link_text}](`{abs_path}`) (use read_file to access)" return match.group(0) # Match markdown link patterns with optional prefix words # Captures: (optional prefix word) [link text] (complete file path including ./) pattern_markdown = ( r"(?:(Read|See|Check|Refer to|Load|View)\s+)?\[(`?[^`\]]+`?)\]\(((?:\./)?[^)]+\.(?:md|txt|json|yaml|js|py|html))\)" ) content = re.sub(pattern_markdown, replace_markdown_link, content, flags=re.IGNORECASE) return content def discover_skills(self) -> List[Skill]: """ Discover and load all skills in the skills directory Returns: List of Skills """ skills = [] if not self.skills_dir.exists(): print(f"⚠️ Skills directory does not exist: {self.skills_dir}") return skills # Recursively find all SKILL.md files for skill_file in self.skills_dir.rglob("SKILL.md"): skill = self.load_skill(skill_file) if skill: skills.append(skill) self.loaded_skills[skill.name] = skill return skills def get_skill(self, name: str) -> Optional[Skill]: """ Get loaded skill Args: name: Skill name Returns: Skill object, or None if not found """ return self.loaded_skills.get(name) def list_skills(self) -> List[str]: """ List all loaded skill names Returns: List of skill names """ return list(self.loaded_skills.keys()) def get_skills_metadata_prompt(self) -> str: """ Generate prompt containing ONLY metadata (name + description) for all skills. This implements Progressive Disclosure - Level 1. Returns: Metadata-only prompt string """ if not self.loaded_skills: return "" prompt_parts = ["## Available Skills\n"] prompt_parts.append("You have access to specialized skills. Each skill provides expert guidance for specific tasks.\n") prompt_parts.append("Load a skill's full content using the appropriate skill tool when needed.\n") # List all skills with their descriptions for skill in self.loaded_skills.values(): prompt_parts.append(f"- `{skill.name}`: {skill.description}") return "\n".join(prompt_parts)