Agent Skills：用“文件夹”封装可复用的 AI 能力

my-skill/
├── SKILL.md          # 主文件：YAML 元数据 + Markdown 指令
├── scripts/          # 可选：可执行代码（Python、Bash 等）
├── references/       # 可选：规则、规范、参考指南
└── assets/           # 可选：图标、模板等资源

import os, re, yaml

class SkillRegistry:
    def __init__(self, skills_dir: str):
        self.skills = {}
        for name in os.listdir(skills_dir):
            path = os.path.join(skills_dir, name, "SKILL.md")
            if not os.path.exists(path):
                continue
            with open(path) as f:
                content = f.read()
            meta = yaml.safe_load(re.match(r"---\n(.*?)\n---", content, re.S).group(1))
            self.skills[meta["name"]] = {
                "description": meta["description"],
                "dir": os.path.dirname(path),
                "loaded": False,
                "content": None,
            }

    def discover(self) -> str:
        """第一层：只返回元数据，供模型判断是否需要"""
        return "\n".join(
            f"- {name}: {s['description']}"
            for name, s in self.skills.items()
        )

    def load(self, name: str) -> str:
        """第二层：按需加载完整指令"""
        s = self.skills[name]
        if not s["loaded"]:
            with open(os.path.join(s["dir"], "SKILL.md")) as f:
                s["content"] = f.read()
            s["loaded"] = True
        return s["content"]

    def run_script(self, name: str, script: str, args: list) -> str:
        """第三层：按需执行脚本"""
        script_path = os.path.join(self.skills[name]["dir"], "scripts", script)
        # 生产环境需沙盒隔离
        import subprocess
        result = subprocess.run(["python", script_path] + args,
                                capture_output=True, text=True, timeout=30)
        return result.stdout

# 使用示例
registry = SkillRegistry("./skills")
system_prompt = f"""可用技能：
{registry.discover()}
判断需要哪个技能后，调用 load_skill 获取完整指令。"""

# 模型返回 {"action": "load_skill", "name": "pdf-toolkit"}
instructions = registry.load("pdf-toolkit")