Agent Skills 运行时¶

# 必需
cp skills/skills.py your_project/
cp frontmatter/frontmatter.py your_project/
cp yaml/yaml.py your_project/

# 可选（用于 BM25 选择）
cp sparse_search/sparse_search.py your_project/

zerodep add skills

from skills import Skill, SkillRegistry, load, loads, validate, to_catalog

from skills import load, loads

# 从目录加载
skill = load("path/to/my-skill")
print(skill.name)           # "my-skill"
print(skill.description)    # "技能描述"
print(skill.instructions)   # 完整 Markdown 正文

# 从文本解析
skill = loads("""---
name: pdf-processing
description: Extract text from PDF files
---
# PDF Processing

When the user asks about PDFs, use this skill.
""")

from skills import Skill, SkillProperties

# 从字典创建
skill = Skill.from_dict({
    "name": "my-tool",
    "description": "Does something useful",
    "instructions": "# My Tool\n\nUse this when...",
})

# 序列化回 SKILL.md 格式（支持往返转换）
md_text = skill.to_markdown()
print(md_text)
# ---
# name: my-tool
# description: Does something useful
# ---
# # My Tool
#
# Use this when...

from skills import SkillRegistry

registry = SkillRegistry()

# 扫描标准 Agent Skills 目录
registry.discover(
    "~/.agents/skills",       # 用户级技能
    ".agents/skills",         # 项目级技能
)

# 递归发现嵌套布局（category/skill/）
registry.discover("~/.agents/skills", recursive=True)

# 覆盖机制：项目级技能优先于用户级技能
registry.discover("~/.agents/skills")           # 用户级
registry.discover(".agents/skills", override=True)  # 项目级覆盖

print(f"发现 {len(registry)} 个技能")
for skill in registry:
    print(f"  - {skill.name}: {skill.description}")

from skills import SkillRegistry, to_catalog

registry = SkillRegistry()
registry.discover("~/.agents/skills")

# 预筛选：100 个技能 -> 最相关的 10 个
matches = registry.select("convert this PDF to markdown", top_k=10)
shortlist = [m.skill for m in matches]

# 只将筛选后的目录注入系统提示词（节省 token）
catalog_xml = to_catalog(shortlist)

# LLM 看到缩减后的目录，自行决定激活哪个技能

# 按最低相关性分数过滤
matches = registry.select("PDF conversion", top_k=10, min_score=0.3)

# 按工具兼容性过滤
matches = registry.select(
    "review this code",
    available_tools=["Bash", "Read", "Write"],
)

# 独立的兼容性过滤函数
from skills import filter_compatible

compatible = filter_compatible(
    registry.list(),
    available_tools=["Bash", "Read", "Write", "Glob"],
)

from skills import Selector, SelectionResult, Skill

class EmbeddingSelector:
    """基于句向量嵌入的自定义选择器。"""

    def __init__(self, model_name: str):
        # 初始化嵌入模型
        ...

    def select(
        self, query: str, skills: list[Skill], top_k: int
    ) -> list[SelectionResult]:
        # 你的嵌入排序逻辑
        ...

# 使用
results = registry.select("query", selector=EmbeddingSelector("bge-m3"))

from skills import validate

problems = validate("path/to/my-skill")
if problems:
    print("验证失败：")
    for p in problems:
        print(f"  - {p}")
else:
    print("技能验证通过！")

from skills import load, to_catalog, compose

skill_a = load("skills/pdf-processing")
skill_b = load("skills/code-review")

# 第一层：目录 XML（所有技能的名称和描述）
catalog = to_catalog([skill_a, skill_b])

# 第二层：激活提示词（选中技能的完整指令）
prompt = skill_a.to_prompt()

# 第二层增强：内联资源文件内容
prompt = skill_a.to_prompt(inline_resources=True)
# 资源文件内容直接包含在 XML 输出中

# 组合多个技能
combined = compose(skill_a, skill_b)