Agent Skills Runtime¶

# Required
cp skills/skills.py your_project/
cp frontmatter/frontmatter.py your_project/
cp yaml/yaml.py your_project/

# Optional (for BM25-based selection)
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

# From a directory
skill = load("path/to/my-skill")
print(skill.name)           # "my-skill"
print(skill.description)    # "What this skill does"
print(skill.instructions)   # Full markdown body

# From text
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

# From a dictionary
skill = Skill.from_dict({
    "name": "my-tool",
    "description": "Does something useful",
    "instructions": "# My Tool\n\nUse this when...",
})

# Serialize back to SKILL.md format (round-trip safe)
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()

# Scan standard Agent Skills directories
registry.discover(
    "~/.agents/skills",       # User-level skills
    ".agents/skills",         # Project-level skills
)

# Recursive discovery for nested layouts (category/skill/)
registry.discover("~/.agents/skills", recursive=True)

# Override: project skills take precedence over user skills
registry.discover("~/.agents/skills")           # user-level
registry.discover(".agents/skills", override=True)  # project overrides

print(f"Found {len(registry)} skills")
for skill in registry:
    print(f"  - {skill.name}: {skill.description}")

from skills import SkillRegistry, to_catalog

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

# Pre-filter: 100 skills -> top 10 most relevant
matches = registry.select("convert this PDF to markdown", top_k=10)
shortlist = [m.skill for m in matches]

# Only inject filtered catalog into system prompt (saves tokens)
catalog_xml = to_catalog(shortlist)

# LLM sees the reduced catalog and decides which skill to activate

# Filter by minimum relevance score
matches = registry.select("PDF conversion", top_k=10, min_score=0.3)

# Filter by tool compatibility
matches = registry.select(
    "review this code",
    available_tools=["Bash", "Read", "Write"],
)

# Standalone compatibility filter
from skills import filter_compatible

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

from skills import Selector, SelectionResult, Skill

class EmbeddingSelector:
    """Custom selector using sentence embeddings."""

    def __init__(self, model_name: str):
        # Initialize your embedding model
        ...

    def select(
        self, query: str, skills: list[Skill], top_k: int
    ) -> list[SelectionResult]:
        # Your embedding-based ranking logic
        ...

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

from skills import validate

problems = validate("path/to/my-skill")
if problems:
    print("Validation failed:")
    for p in problems:
        print(f"  - {p}")
else:
    print("Skill is valid!")

from skills import load, to_catalog, compose

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

# Level 1: Catalog XML (name + description for all skills)
catalog = to_catalog([skill_a, skill_b])
# <available_skills>
# <skill><name>pdf-processing</name>...</skill>
# <skill><name>code-review</name>...</skill>
# </available_skills>

# Level 2: Activation prompt (full instructions for selected skill)
prompt = skill_a.to_prompt()
# <skill_content name="pdf-processing">
# [full markdown instructions]
# <skill_resources>
# <file>scripts/extract.py</file>
# </skill_resources>
# </skill_content>

# Level 2 with inlined resource contents
prompt = skill_a.to_prompt(inline_resources=True)
# Resource file contents are included directly in the XML output

# Compose multiple skills
combined = compose(skill_a, skill_b)