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
Metadata
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 | Provenance | Actions |
|---|---|---|---|---|
| haiku_skills-0.18.1.tar.gz | 190.0 kB | Without provenance | Details for haiku_skills-0.18.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| haiku_skills-0.18.1-py3-none-any.whl | Python 3 | none | any | Details for haiku_skills-0.18.1-py3-none-any.whl |
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
|
Security for haiku.skills 0.18.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.