py-llm-skills 0.1.0

Add your description here

LLM Skills

A Python SDK for building AI Agent Skills that strictly follow the official Anthropic SKILL.md standard.

Designed to be the standard implementation for modular AI tooling, this SDK enables developers to build portable, secure, and highly capable skills for Claude, OpenAI, and other LLMs with function calling support. It handles validation, discovery, and progressive loading, so you can focus on building intelligent capabilities.

Why LLM Skills?

Building agentic tools today is often messy and inefficient. Developers face three core problems:

1. Token Bloat: Injecting every possible tool definition into the system prompt exhausts context windows and increases cost.
2. Vendor Lock-in: Tools written for OpenAI function calling often don't work with Claude or other models without significant rewriting.
3. Spaghetti Code: Hard-coding tool logic directly into your agent making it impossible to share or reuse capabilities across projects.

LLM Skills solves this by treating skills as portable data packages.

• Standardized: Write once using SKILL.md and run anywhere (OpenAI, Claude, Custom Agents).
• Efficient: Uses Progressive Disclosure to load heavy instructions and scripts only when the model actually decides to use the skill.
• Discoverable: The built-in Router allows your agent to choose from hundreds of skills dynamically, rather than being limited to a static set of tools.

How It Works

The SDK implements the Anthropic 4-Phase Loading architecture to optimize token usage and context management:

flowchart TD
    subgraph Discovery ["Phase 1: Discovery"]
        direction TB
        A[User Query] -->|Router| B{Select Skill}
        B -->|Match| C[Load Metadata]
        C -->|Description| D[System Prompt]
    end

    subgraph Loading ["Phase 2: Loading"]
        direction TB
        D -->|Tool Use| E[Load Content]
        E -->|Read| F[SKILL.md]
        E -->|Discover| G[Resources]
        G --> H["/scripts/"]
        G --> I["/examples/"]
        G --> J["/references/"]
    end

    subgraph Execution ["Phase 3: Execution"]
        direction TB
        F -->|Instructions| K[LLM Context]
        K -->|Code| L[Execute Script]
        L -->|Result| M[Final Response]
    end

    style Discovery fill:#e1f5fe,stroke:#01579b
    style Loading fill:#f3e5f5,stroke:#4a148c
    style Execution fill:#e8f5e9,stroke:#1b5e20

    linkStyle default stroke-width:2px,fill:none,stroke:black;

Features

• Standard Compliance: Validates SKILL.md against official Anthropic rules (name format, length limits) to ensure compatibility with the Claude API.
• Progressive Disclosure: Efficiently manages token context by loading only essential metadata initially, then pulling in full instructions and companion resources (like scripts or reference docs) only when the skill is actually used.
• Auto-Discovery: Automatically finds and categorizes companion files (scripts/, examples/, references/) within skill directories, making them available to your agent.
• Secure by Default: Built-in path traversal protection ensures skills cannot access files outside their directory.
• Universal Patterns:
  • Prompt Injection: Use Patterns.file_based_prompt to inject skill instructions directly into your system prompt.
  • Function Calling: Use to_tool_definition() to generate JSON schemas for OpenAI or Claude tool use.
  • Native Anthropic: Use to_anthropic_files() to bundle and upload skills directly to the Anthropic API for containerized execution.

Installation

We recommend using uv for modern Python project management:

uv add py-llm-skills

Or install with pip:

pip install py-llm-skills

Quick Start

1. Define a Skill

Create a directory skills/weather/ and add a SKILL.md. Notice how we key-value pair metadata for the router and keep instructions clear.

---
name: weather
description: Get current weather information for a given location.
version: 1.0.0
input_schema:
  type: object
  properties:
    location: {type: string, description: "City and state, e.g. San Francisco, CA"}
  required: [location]
---
You are a weather assistant. Fetch real-time data for the user's location.

2. Use in Python

from py_llm_skills.core import SkillRegistry, Skill
from py_llm_skills.patterns import Patterns

# Load all skills from a directory
registry = SkillRegistry()
registry.register_directory("./skills")

# Get a specific skill by name
weather = registry.get_skill("weather")

# Pattern 1: Inject into system prompt
prompt = Patterns.file_based_prompt([weather])

# Pattern 2: Use as OpenAI / Claude tool
tool_def = weather.to_tool_definition()

# Pattern 3: Upload to Anthropic Skills API
# This bundles the SKILL.md and all discovered scripts/resources
files = weather.to_anthropic_files()

3. Upload to Claude (Anthropic Skills API)

Directly upload your local skills to the Anthropic beta API for server-side execution:

import anthropic
from py_llm_skills.llm.claude import AnthropicSkillManager

client = anthropic.Anthropic()
manager = AnthropicSkillManager(client)

# Upload a skill and get a skill_id
skill_id = manager.upload_skill(weather)

# Use in messages via the container parameter
container = manager.format_container_param([skill_id])

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details on how to set up your development environment and submit pull requests.

License

MIT