File size: 8,817 Bytes
dc893fb |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 |
"""
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)
|