haiku.skills
A skill system for pydantic-ai agents, implementing the Agent Skills specification.
Load skills from SKILL.md directories, Python entrypoints, or MCP servers and attach them to your agent as a SkillsCapability or SkillToolset. Skills run as isolated sub-agents by default, keeping your main agent's tool space clean regardless of how many skills you load.
Quick start
uv add haiku.skills
from pydantic_ai import Agent
from haiku.skills import SkillsCapability
agent = Agent(
"anthropic:claude-sonnet-4-5-20250929",
capabilities=[SkillsCapability(use_entrypoints=True)],
)
result = await agent.run("Analyze this dataset.")
print(result.output)
Or with explicit control over the toolset:
from pathlib import Path
from pydantic_ai import Agent
from haiku.skills import SkillToolset, build_system_prompt
toolset = SkillToolset(skill_paths=[Path("./skills")])
agent = Agent(
"anthropic:claude-sonnet-4-5-20250929",
instructions=build_system_prompt(toolset.skill_catalog),
toolsets=[toolset],
)
How it works
Two execution modes:
- Sub-agent mode (default): exposes a single
execute_skilltool. Each invocation spins up a focused sub-agent with only that skill's instructions, tools, and token budget. The main agent never sees skill internals. - Direct mode (
use_subagents=False): exposes skill tools directly to the main agent. No sub-agent LLM loops, lower latency, and the agent retains tool results in its conversation context.
Skill sources
Skills are discovered automatically and can come from three sources:
- Filesystem: directories containing a SKILL.md file with scripts in Python, JavaScript, TypeScript, or shell
- Entrypoints: Python packages that register via the
haiku.skillsentry_points group, with typed in-process tools, per-skill Pydantic state, and zero-config discovery - MCP servers: wrap any MCP server as a skill with
skill_from_mcp
Additional Features
- Per-skill state: Pydantic state models tracked per namespace; state deltas emitted as JSON Patch for the AG-UI protocol
- AG-UI streaming: skill tool calls and state changes stream as
ActivitySnapshotEventandStateDeltaEventfor real-time UIs - Custom dependencies and lifespan: declare a
deps_typeto extend what skill tools see onctx.deps; optionally attach alifespanasync context manager to allocate per-invocation resources (DB clients, caches, counters) that are disposed when the skill run ends - Signing and verification: identity-based skill signing via sigstore, verified at discovery time
- CLI:
haiku-skills list,validate,sign,verify, and an interactivechatTUI
Built-in skills
The repo ships several skill packages as references and for immediate use:
| Skill | Description |
|---|---|
web |
Search (Brave) and fetch web pages with readability extraction |
code-execution |
Sandboxed Python execution via Monty |
image-generation |
Image generation with await llm() support |
gmail |
Gmail integration |
notifications |
System notifications |
Each is a standalone package: uv add haiku-skills-web, uv add haiku-skills-code-execution, etc. They register via the haiku.skills entrypoints group and are discovered automatically.
Documentation
Full documentation at ggozad.github.io/haiku.skills.
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for haiku.skills 0.18.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| haiku_skills-0.18.1.tar.gz | 190.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| haiku_skills-0.18.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 224.6 kB
Release files / haiku_skills-0.18.1.tar.gz
| Download URL | haiku_skills-0.18.1.tar.gz |
|---|---|
| Size | 190.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
36edd612a91a897459a5218b79c207372e33670b89b312631f3c69bc9b211dc5
|
|
BLAKE2b-256 checksum How to use checksums |
ae090984a5ac416453ac2d170fde5ea973ed0700a21ed220d13d1d9ca2127b7f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.14
|
Release files / haiku_skills-0.18.1-py3-none-any.whl
| Download URL | haiku_skills-0.18.1-py3-none-any.whl |
|---|---|
| Size | 34.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b6f8b31d54a0b3a8dfd54a53b9cdcaa45ddedc65dd0349c8db7ba8a59b0f891e
|
|
BLAKE2b-256 checksum How to use checksums |
7824280e4d72b09136086b56658b9fb81d620b0365844f4eca50ab5c7e99f74b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.14
|
