一个面向AI代理的无框架技能系统，实现了渐进披露——一种高效的上下文管理模式。该项目演示如何从专有AI系统（如Claude Skills）中提取成功的模式，并将其应用于像Pydantic AI这样的开放框架中。

主要特色

• 渐进披露：技能按需加载指令和资源，消除上下文窗口限制
• 框架无关性：技能适用于任何AI框架，不限于特定供应商
• 类型安全：全套Pydantic模型及类型提示
• 可扩展：通过简单的目录结构轻松添加新技能
• 生产准备：包含全面的测试模式和示例

什么是进步披露？

渐进披露是一种高效管理人工智能上下文的技术。技能不会自动加载到系统提示中，而是分为三个层级加载：

这种模式允许代理访问数百种技能，而不会淹没上下文窗口。

快速启动

先决条件

• Python 3.11 或更高版本
• UV - 快速 Python 包管理器

Custom Skill-Based Pydantic AI Agent

A framework-agnostic skill system for AI agents that implements progressive disclosure - a powerful pattern for managing context efficiently. This project demonstrates how to extract successful patterns from proprietary AI systems (like Claude Skills) and implement them in open frameworks like Pydantic AI.

Key Features

• Progressive Disclosure: Skills load instructions and resources on-demand, eliminating context window constraints
• Framework Agnostic: Skills work with any AI framework, not locked to a specific vendor
• Type Safe: Full Pydantic models and type hints throughout
• Extensible: Easy to add new skills by following a simple directory structure
• Production Ready: Includes comprehensive testing patterns and examples

What is Progressive Disclosure?

Progressive disclosure is a technique for managing AI context efficiently. Instead of loading all possible instructions into the system prompt, skills are loaded in three levels:

Level 1: Metadata (~100 tokens per skill)
    - Name and brief description in system prompt
    - Agent decides which skill might be relevant

Level 2: Full Instructions (loaded on-demand)
    - Complete SKILL.md with detailed instructions
    - Only loaded when agent chooses to use the skill

Level 3: Resources (loaded on-demand)
    - Reference files, scripts, and other resources
    - Only loaded when instructions reference them

This pattern allows an agent to have access to potentially hundreds of skills without overwhelming the context window.

Quick Start

Prerequisites

• Python 3.11 or higher
• UV - Fast Python package manager
• An API key for an LLM provider (OpenRouter, OpenAI, Anthropic, etc.)

Installation

1. Install UV (if not already installed):

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Clone the repository:

git clone https://github.com/coliam00/custom-agent-with-skills.git
cd custom-agent-with-skills

3. Sync dependencies:

uv sync

This creates a virtual environment and installs all dependencies automatically.

4. Configure environment variables:

Copy .env.example to .env and set your API key:

cp .env.example .env

Edit .env with your API credentials:

# LLM Provider Configuration
LLM_PROVIDER=openrouter
LLM_API_KEY=sk-or-v1-your-api-key-here
LLM_MODEL=anthropic/claude-haiku-4.5
LLM_BASE_URL=https://openrouter.ai/api/v1

Running the Agent

Start the CLI agent:

uv run python -m src.cli

You’ll see a Rich-based interface where you can interact with the agent. Try asking:

• “What’s the weather in New York?”
• “Find papers about machine learning”
• “What can I make with chicken and garlic?”
• “What time is it in Tokyo?”

Included Skills

Weather Skill